\input texinfo @c -*- Mode: Texinfo -*-
@c gcc-st.tex -- How to install and use GCC on your Atari ST or TT
@c
@c Copyright (C) 1991, 1992, 1993 Frank Ridderbusch
@c
@c Author          : Frank Ridderbusch T35
@c Created On      : somtime during 1990
@c Last Modified By: Frank Ridderbusch
@c Last Modified On: Sat Jul  3 21:40:14 1993
@c Update Count    : 149
@c Status          : Beware, this version is not finished yet.
@c
@c HISTORY
@c 15-Apr-1993		Frank Ridderbusch
@c    Last Modified: Thu Apr 15 14:11:10 1993 #115 (Frank Ridderbusch)
@c    Restructurize the utilities section, update options of utilities,
@c    include a master menu, updates all over the place. Make this file
@c    useable with outline-minor-mode.
@c 27-Oct-1992		Frank Ridderbusch
@c    Last Modified: Tue Oct 27 23:30:20 1992 #90 (Frank Ridderbusch)
@c    Include the new options for base relative compilation.
@c 20-Dec-1991		Frank Ridderbusch T35
@c    Last Modified: Fri Dec 20 11:34:04 1991 #46 (Frank Ridderbusch T35)
@c    Include chapter about C++ compiler driver options
@c 20-Dec-1991		Frank Ridderbusch T35
@c    Last Modified: Fri Dec 20 08:58:56 1991 #44 (Frank Ridderbusch T35)
@c    Restructuring the utilities chapter. Various minor changes.
@c 6-Dec-1991		Frank Ridderbusch T35
@c    Last Modified: Fri Dec  6 11:21:19 1991 #26 (Frank Ridderbusch T35)
@c    Run this file through ispell.
@c
@c TODO
@c    - Include a comment about availability of texinfo214b.
@c    - Describe __MBASESTR__ (cpp predefine)
@c    - Include hint about GDB stopping after run.
@c
@c $Log$
@comment %**start of header
@settitle GCC for the Atari ST, TT and Falcon
@setfilename gcc-st
@comment %**end of header

@iftex
@finalout
@c @smallbook
@c @cropmarks
@end iftex

@c We are formatting for GCC 2.x and GCC 1.x
@set gcc1
@set gcc2

@ifinfo
@unnumbered Introduction

This file documents the usage of the GNU C compiler on the Atari ST, TT
and Falcon computers and contains material from other copyrighted GNU
manuals. The version of the C and C++ compiler, on which this manual is
based are mainly 1.40 and 1.40.0 and some facts are from GCC 2.x. This
manual does not yet cover GCC 2.x in it's complete beauty. (I wonder, if
it ever will?)

Copyright (C) 1988, 1989, 1990 Free Software Foundation, Inc.
	      1990, 1991, 1992, 1993 Frank Ridderbusch

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU CC General Public License'' is included exactly a
s in the original, and provided that the entire resulting derived work
is distributed under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU CC General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.
@end ifinfo

@titlepage
@title GCC for the Atari ST, TT & Falcon
@subtitle Using the GNU C-Compiler on the Atari ST, TT & Falcon computers
@subtitle @today
@author by Frank Ridderbusch

@page
@vskip 0pt plus 1filll
Copyright @copyright{}  1988, 1989, 1990 Free Software Foundation, Inc.

Copyright @copyright{}  1990, 1991, 1992, 1993 Frank Ridderbusch

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU CC General Public License'' is included exactly
as in the original, and provided that the entire resulting derived work
is distributed under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
<except that the section entitled ``GNU CC General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.
@end titlepage
@setchapternewpage off
@page

@ifinfo
@node     Top,        Copying, (dir),     (dir)
@comment  node-name,  next,    previous,  up
@ichapter Introduction

This manual documents how to install and run the GNU C compiler on
the Atari ST & TT computers.

Beware, this version is not finished yet. GCC 2.x is not yet completly
covered, but since the majority of options is equal to GCC 1.x, this is
not a real problem. Also GAS 1.92 is pending.

@end ifinfo
@menu
* Copying::             GNU CC General Public License says
                         how you can copy and share GNU CC.
* Contributors::        People who have contributed to GNU CC, GNU C++
                         and to the port for the Atari ST.
* Introduction::	Some introductory comments.
* Installing GCC::      How to install GCC on your Atari ST.
* Installing Gxx::	How to install G++ on your ST.
* Memory Requirements:: Some comments about the amount of memory GCC
                         uses and what setup is usefull under MiNT.
* The C-Compiler Driver::
                        Command options supported by @samp{gcc.ttp}.
* The Cxx-Compiler Driver::
                        Command options supported by @samp{g++.ttp}.
* The Preprocessor::    Command options and predefined macros supported
                        by @samp{gcc-cpp.ttp}.
* The Assembler::       Command options supported by @samp{gcc-as.ttp}.
* The Utilities::       How to use the support programs like @samp{gcc-ld.ttp},
                         @samp{gcc-ar.ttp}, @samp{sym-ld.ttp} etc.
* Debugging::

* Concept Index::
* Command Options::

 --- The Detailed Node Listing ---

Installing GCC

* Executables::		Installation of the executable programs.
* Libraries::		Installation of the libraries.
* Headers::		Installation of the header files.
* Gulam notes::		Some comments for using the CLI gulam.

The Preprocessor

* Invoking CPP::        Command options supported by @samp{gcc-cpp.ttp}.
* Predefined Macros::   List of predefined macros

The GNU Assembler (GAS)

* Invoking AS::         Command line options supported by @samp{gcc-as.ttp}.
* Syntax::              Description of the assembler syntax.
* Pseudo Opcodes::      Pseudo Opcodes supported by @samp{gcc-as.ttp}.
* Asmtrans::            Converting Motorola Assembler Syntax

Syntax

* Registers::		This section describes the register names and
			 addressing modes.
* Labels::		This section explains the rules for labels and
			 identifier.
* Comments::		The rules for inserting comments.
* Constants::		Numerical and string constants.
* Assignments::		How to do assignments and the available operators.
* Segments::		About segments, location counters and labels.
* Types::		About what type a label or a symbol can be.

The Utilities

* The Linker::          Command options supported by @samp{gcc-ld.ttp}
* The Archiver::        Command options supported by @samp{gcc-ar.ttp}
* Miscellaneous::       Commands to modify an existing executables or
                         obtain information from object or executable
                         files.

Miscellaneous Utilities

* gcc-nm.ttp::          List symbols from an object file or library.
* cnm.ttp::             List symbols attached to an executable.
* gcc-size.ttp::        List sizes of segments in object files.
* printstk.ttp::        Print the current value @code{_stksize}.
* fixstk.ttp::          Set the value of @code{_stksize}.
* toglclr.ttp::         Modify some program header bits.
* xstrip.ttp::          Strip an executable from symbol table.
* size68.ttp::          List sizes of segments and status of program
                         header bits of an executbale.
@end menu

@node     Copying,    Contributors, Top,       Top
@comment  node-name,  next,         previous,  up
@include gpl.texinfo

@node     Contributors, Introduction, Copying,   Top
@comment  node-name,    next,         previous,  up
@unnumbered Contributors to GNU CC

  In addition to Richard Stallman, several people have written parts
of GNU CC.

@itemize @bullet
@item
The idea of using RTL and some of the optimization ideas came from the
U. of Arizona Portable Optimizer, written by Jack Davidson and
Christopher Fraser.  See ``Register Allocation and Exhaustive Peephole
Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
857-866.

@item
Paul Rubin wrote most of the preprocessor.

@item
Leonard Tower wrote parts of the parser, RTL generator, RTL
definitions, and of the Vax machine description.

@item
Ted Lemon wrote parts of the RTL reader and printer.

@item
Jim Wilson implemented loop strength reduction and some other
loop optimizations.

@item
Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
the support for the SONY NEWS machine.

@item
Charles LaBrec contributed the support for the Integrated Solutions
68020 system.

@item
Michael Tiemann of MCC wrote most of the description of the National
Semiconductor 32000 series cpu.  He also wrote the code for inline
function integration and for the SPARC cpu and Motorola 88000 cpu
and part of the Sun FPA support.

@item
Jan Stein of the Chalmers Computer Society provided support for
Genix, as well as part of the 32000 machine description.

@item
Randy Smith finished the Sun FPA support.

@item
Robert Brown implemented the support for Encore 32000 systems.

@item
David Kashtan of SRI adapted GNU CC to the Vomit-Making System.

@item
Alex Crain provided changes for the 3b1.

@item
Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
the 9000 series 300.

@item
William Schelter did most of the work on the Intel 80386 support.

@item
Christopher Smith did the port for Convex machines.

@item
Paul Petersen wrote the machine description for the Alliant FX/8.
@end itemize

Aside from Michael Tiemann, who worked out the front end for GNU C++,
and Richard Stallman, who worked out the back end, the following people
(not including those who have made their contributions to GNU CC) should
not go unmentioned.

@itemize @bullet
@item
Doug Lea contributed the GNU C++ library.  This includes support for
streams, obstacks, structured files, and other public service objects.

@item
Doug Schmidt has spent countless hours pursuing bugs in this compiler
for sport.  He also wrote a perfect hash function generator in GNU C++
which was used to generate a replacement for the keyword recognizer in
the lexical analyzer for both GNU CC and GNU C++.

@item
Marc Shapiro and Phillipe Gautron helped me implement features needed
for the SOR distributed object management environment.

@item
Dirk Grunwald made the collect program usable under COFF.

@item
Angel Li adapted GNU C++ to VMS.

@item
Ron Cole provided additional help getting GNU C++ working on COFF-based
systems.

@item
James Clark wrote a name demangler for the GNU C++ naming scheme, and
integrated it with the linker.

@item
Michael Powell and Jim Mitchell helped design the GNU C++
exception handling mechanism.
@end itemize

The following people contributed specially to the version for the
Atari ST & TT.

@itemize @bullet
@item
John R. Dunning did the original port to the Atari ST.

@item
Jwahar R. Bammi improved the port and the libraries.

@item
Eric R. Smith wrote lots of code for the libraries.

@item
David Boyce ported G++ 1.39.1 and the libg++ 1.39.0 to the ST.

@item
The following is a not necessarily complete list of people who either
contributed code or bugfixes to the libraries: Michal Jaegermann, Scott
Kolodzieski, Andreas Schwab, Frank Celler, Edgar Roeder, Kai-Uwe Bloem,
Allan Pratt, Jens Tingleff, Thomas Koenig, Markus Nick. Apologies to
those I forgot to mention.

@item
Frank Ridderbusch compiled this manual specially for the Atari ST.
@end itemize
@page

@node     Introduction, Installing GCC, Contributors , Top
@comment  node-name,    next,           previous,  up
@unnumbered Introduction
@cindex Introduction

  This manual documents how to install and run the GNU C compiler on the
Atari ST & TT computers. It does not give an introduction in C or M68000
assembler. There is enough material on both subjects available. The
user, who is familiar with a C compiler, that runs on a U**x system,
should have no trouble at all to get GNU C running on the Atari ST. This
manual was compiled from existing GNU manuals and various bits and
pieces from John R. Dunning and Jwahar R. Bammi.

  The sections, which describe the compiler driver, the preprocessor and
the G++ compiler driver are nearly verbatim copies of sections in the
respective manuals. The original manuals (@i{Using and Porting GNU CC}
and @i{The C Preprocessor}), were written by Richard M. Stallman and
Michal D. Tieman (@i{User's Guide to GNU C++}). All of these three
documents are copyright @copyright{} The Free Software Foundation. I
modified these sections by removing material, which described features
of GNU C for systems like Vaxen or Suns. To keep this manual reasonably
compact, I extracted only the sections, which describe the supported
command options (and predefined macros in case of the preprocessor). If
the user is interested in the extensions and details, which are
implemented in GNU C, he has to refer to the original manuals. Whether
all described options are useful on the Atari has to be decided.

  The facts, which are presented in the assembler and utility sections
are mostly derived from the sources of the respective programs (from a
cross compiler kit by J. R. Bammi based on GNU C 1.31), which were
available to me. Other facts were gathered by try and error. So, these
sections may be a bit shaky.

  The first version of this manual was based on GCC 1.37.1. Then, GCC
1.40 and G++ 1.39.1 became available. The most noticeable differences
were some new options (@samp{-mint}, @samp{-G}, @samp{-z}) and the
extended symbol table format. In the beginning of 1992 the FSF released
GCC 2.x. In this release GCC and G++ were merged into one large package.
At the time of this writing the current version for the Atari is 2.4.5
with patchlevel 1. This manual doesn't cover all new command line
options from GCC 2.3.3, but only the most valuable (in the authors
opinion). @emph{The coverage of GCC 2.x is not yet complete. Also, GAS
1.92 is pending.} Patchlevel 4 of GCC 2.2.2 and later versions in
connection with MiNT 0.96 pl14 allow the creation of executables, whose
text sections can be shared. This means, if multiple copies of the same
program are running, the actual program code is memory only once, while
each running program has it private data section.

  Additionally two flavours of libraries are present. One version, which
is now mostly maintained by J.R.Bammi, is for the ST running the native
TOS operating system. The other flavour was originally maintained by
E.R.Smith, since Eric moved to Atari to continue development of MultiTOS
Nick Castellano (Email: entropy@@terminator.rs.itd.umich.edu) took over.
This version is specially modified to support MiNT, the multitasking TOS
extension, also from E.R.Smith. BTW, MiNT has now become the base of
Atari's multitasking TOS. It is the aim of both maintainers to keep the
libraries in sync as much as possible and possibly merge them together
in the future.

  The best place to look for all the components (binaries and sources)
is at the moment the Atari archive at terminator. The internet address
for anonymous ftp is atari.archive.umich.edu.  Also a mail server called
BART is active. Send a message with the word @samp{help} in it to the
address atari@@atari.archive.umich.edu and BART will explain himself.
The maintainers of this archive post a monthly message to the USENET
newsgroup @samp{comp.sys.atari.st}, which explains, how to get things
from the archive. The packaging of the files may be different as it is
explained below.@refill

  If you find any errors or typos in this manual or have any other
comments, please let me know. My email address is (the SNI addresses are
prefered):

@display
ridderbusch.pad@@sni-usa.com
(Amerika (North & South))
ridderbusch.pad@@sni.de
(Rest of world)
Frank_Ridderbusch@@pb.maus.de
(MausNet, a FIDO like network in Germany)
@end display
@page

@node     Installing GCC, Installing Gxx, Introduction, Top
@comment  node-name,      next,           previous,     up
@chapter Installing GCC
@cindex Installing GCC
@cindex GCC Installation
@cindex Installation

  There are basically three components, which make up a basic compiling
system and which have to be installed. Each component is accessed via an
environment variable. This three components are:

@table @strong
@item The executables
These are accessed via the normal @code{PATH} variable, by which all
other programs are found and the variable @code{GCCEXEC}.

@item The header files
The preprocessor accesses the header files via the variable
@code{GNUINC}. Any C++ header files are accessed via @code{GXXINC}

@item The libraries
The linker finds the startup file and the required libraries via the
variable @code{GNULIB}. The C++ library also belongs into this
directory.
@end table

  All this stuff basically assumes that you're using a CLI (command line
interpreter). A really good choice is Gulam, which has very nice set of
features, but there are quite a number of other CLI's around, which also
might do the job. If want as much U**x feeling as possible, you might
consider either @file{ash}, which is compatible to the Bourne shell
(ported by Stefan Neuhaus), or E.R.Smiths port of @file{tcsh} or Scott
Kolodzieskis port of BASH 1.12.

  Apart from the CLI you definitely should get yourself a @i{make}
utility. Again, good choices here are either the GNU Make, which offers
nearly the complete U**x make functionality on the ST or the PDMAKE,
which has only the core make functionality, but has on the other hand
the advantage, that it requieres fewer system resources.

  I suggest the following directory structure on your disk partition:

@table @file
@item \gnu\bin
for all executable programs. The compiler driver finds the executables
in this directory by looking up the environment variable @code{GCCEXEC}.

@item \gnu\lib
for the startup object modules and the libraries. The linker find the
startup code and the libraries in this directory by looking up the
variable @code{GNULIB}.

@item \gnu\include
for the header files. The preprocessor finds the include file in this
directory by looking up the environment variable @code{GNUINC}.
@end table

  With earlier versions of GNU CC it was only allowed to put one path
into the variables @code{GNULIB} and @code{GNUINC}. GCC 1.37 and later
allows you to put several paths into these variables, which are
separated by either a @samp{,} or a @samp{;}. All the mentioned paths
are searched in order to locate a specific file. However the startup
module @file{crt0.o} is @strong{only} looked for in the first directory
specified in @code{GNULIB}. If the preprocessor can't find a include
file in one of the directories specified by @code{GNUINC}, it will also
search the paths listed in @code{GNULIB}.@refill

@menu
* Executables::		Installation of the executable programs.
* Libraries::		Installation of the libraries.
* Headers::		Installation of the header files.
* Gulam notes::		Some comments for using the CLI gulam.
@end menu

@node     Executables, Libraries, Installing GCC, Installing GCC
@comment  node-name,   next,      previous,       up
@section Installing the Executables
@cindex Installing the Executables
@cindex Executables Installation

  The compressed archive of the GNU C compiler binary distribution
contains the 'common' executables of the GNU compiler. That means the
compiler driver (@file{gcc.ttp}), the preprocessor (@file{gcc-cpp.ttp}),
the main body (@file{gcc-cc1.ttp}), the assembler (@file{gcc-as.ttp})
and the linker (@file{gcc-ld.ttp}), but depending from where you got
your GCC the packaging might be different. The just mentioned programs
are the absolute minimum, if you want to write C programs. To be
comfortable, you should get the following support programs:

@table @file
@item gcc-ar.ttp
is the object library maintainer.

@item gdb.ttp
is the GNU debugger 2.6 modified for the Atari ST. John Dunning did the
original port to the Atari. Since then Jwahar Bammi has extensively
hacked it. GDB now uses DBX debugging information in the object files.
This requires an assembler with version 1.36 or greater. The latest
version is patchlevel 18.

In the meantime a new gdb port is available. This port is based on GDB
3.5 and requires MiNT 0.96 pl14 or later or MultiTOS. This port was done
by Andreas Schwab (MiNT 0.96 needs a little patch, which is included).

Some time later Andreas announced the port of GDB 3.6, which is only
available in source form at the time of this writing.

@item sym-ld.ttp
creates the symbol file needed with GDB.

@item gcc-nm.ttp
prints the symbols of a GNU object library or an object file.

@item cnm.ttp
prints the symbol table of a GEMDOS executable.

@item fixstk.ttp
@itemx printstk.ttp
are used to modify and print the current stack size of an
executable.

@item toglclr.ttp
TOS 1.4 users can toggle the clear above BSS to end of TPA flag
for the GEMDOS loader. A newer version of @file{toglclr.ttp} also allows
to toggle the loader bits, that were introduced with TOS versions 2.x
and 3.x.

@item size68.ttp
This program list the values of the TEXT, DATA, and BSS sections of a
ready to run executable.

@item xstrip.ttp
removes the symbol table from an executable.
@end table

  All this files should go in @samp{\gnu\bin\} directory on your gnu
disk. I personally keep my executables in the directory
@file{e:\gnu\bin}. You should than extend the search path of your CLI to
include this directory or you move the compiler driver @file{gcc.ttp}
and the files, which are @strong{not} invoked by @file{gcc.ttp}
(@file{gcc.ttp} calls @file{gcc-cpp.ttp}, @file{gcc-cc1.ttp},
@file{gcc-as.ttp} and @file{gcc-ld.ttp}) into the directory, where you
keep your other executables. The next step is to actually define
@code{GCCEXEC}. @file{gcc.ttp} uses this variable to locate the
preprocessor, compiler, assembler and the linker. @code{GCCEXEC}
contains a device/dir/partial-pathname, which not only consists of the
directory, where the executables are kept, but also a common prefix,
which is @samp{gcc-}. Assuming you also put the executables in the
directory as described above, @code{GCCEXEC} would contain
@samp{e:\gnu\bin\gcc-}. The value is the same, you would give the
compiler driver with the @samp{-B} option.@refill
@cindex GCCEXEC (env. variable)

  Then you should define a variable called @code{TEMP}. During
compilation the output of the various intermediate stages is kept here.
The variable must @strong{not} contain a trailing backslash. If you have
enough memory, @code{TEMP} should point to a ramdisk.@refill
@cindex TEMP (env. variable)

  There is another set of executables. They are definitely available
from atari.archive.umich.edu, somewhere in the @samp{Mint} directory.
Other ftp archive in Europe also have them. This set is compiled with
the @samp{-mbaserel} option and linked with the MiNT libraries. They
functional identical to the above described programs, except they behave
a little better when MiNT is running (they can be interupted better and
can work on a Minix file system).

@node     Libraries, Headers, Executables, Installing GCC
@comment  node-name, next,    previous,    up
@section Installing the libraries
@cindex Installing the Libraries
@cindex Library Installation

  The next thing to do is to install the libraries. The distributed
archive contains the following libraries (again, the packaging may
vary):@refill

@cindex Libraries
@table @file
@item crt0.o
@itemx gcrt0.o
are the startup object modules. The file @file{gcrt0.o} instead of
@file{crt0.o} is used, if the sources files are compiled for execution
profiling (the @samp{-pg} option).@refill

@item gnu.olb
@itemx gnu16.olb
are the standard libraries, the usual @samp{libc} on other systems.

@item curses.olb
@itemx curses16.olb
are ports of the BSD curses.

@item gem.olb
@itemx gem16.olb
contain the Atari ST Aes/Vdi/FSM-GDOS bindings.

@item iio.olb
@itemx iio16.olb
contain the integer only @samp{printf} and @samp{scanf} functions.

@item pml.olb
@itemx pml16.olb
are the portable math libraries.

@item termcap.olb
@itemx termcap16.olb
are for the pure @samp{termcap} support.

@item widget.olb
@itemx widget16.olb
are a small widget based on @samp{curses}
@end table

  All these libraries go to a place described by the environment variable
@code{GNULIB}. Again this variable must @strong{not} contain a trailing
backslash. Staying with the above example, I've set the variable to
@samp{e:\gnu\lib}. The libraries, which have a 16 in their names were
compiled with the @samp{-mshort} option. This makes integers the same
size as shorts.@refill
@cindex GNULIB (env. variable)

  If you like to write programs for MiNT, the TOS multitasking extension
from E.R.Smith, you might consider to replace @file{gnu.olb},
@file{gnu16.olb}, @file{iio.olb} and @file{iio16.olb} with the libraries
supplied by Eric Smith. The source and the binaries of these libraries
can also be retrieved from the Atari archive at terminator. The files
are @file{mntlib@var{xx}.zoo} for the sources and
@file{mntolb@var{xx}.zoo} for the binaries. They are found in the
@file{mint} directory. @var{xx} is the version number, currently 24.
Programs written with this libraries will also run under TOS, as long no
MiNT specific features have been used. (@xref{The C-Compiler Driver}, for
more info on compiling programs for MiNT (the @samp{-mint} option))

  Another option is to have both sets of libraries installed. For this
you have to rename the MiNT libraries according to the following scheme:

@itemize @bullet
@item
@file{crt0.o} @result{} @file{mcrt0.o}

@item
@file{gcrt0.o} @result{} @file{mgcrt0.o}

@item
@file{gnu.olb} @result{} @file{mint.olb}

@item
@file{gnu16.olb} @result{} @file{mint16.olb}
@end itemize

  To select these files instead of the standard TOS versions and to
activate the MiNT specific portions of the header files you have to
include the @samp{-mint} option in the @file{gcc.ttp} command line.

  With GCC 2.2.2 pl4 and later it is possible to have another set of
libraries of either the standard TOS or the MiNT libs. These new sets
are named as above plus a leading @samp{b}. The @samp{b} indicates, that
these files have been compiled with the @samp{-mbaserel} option. To
actually make use of these new libraries, you have to be running MiNT
0.96 patchlevel 14. They are totally useless under plain TOS.
Additionally you need a linker with at least patchlevel 32.

  With the option @samp{-mbaserel} it is possible under MiNT to create
executables, whose text (program code) section may be shared. (@xref{The
C-Compiler Driver}, for more info on compiling programs for with shared
text section (the @samp{-mbaserel} option).) The following table gives
an overview over the various files, which are used for linking depending
on the compiler options.

The following startup modules used:

@table @file
@item bcrt0.o
if @samp{-mbaserel} and no @samp{-mint}.

@item bmcrt0.o
if @samp{-mbaserel} and @samp{-mint}

@item bgcrt0.o
if @samp{-mbaserel} and no @samp{-mint} and @samp{-pg}

@item bmgcrt0.o
if @samp{-mbaserel} and @samp{-mint} and @samp{-pg}
@end table

The library files are used as follows (from the linker):

@table @samp
@item -lbgnu16
if @samp{-mbaserel} and @samp{-mshort} and no @samp{-mint}.

@item -lbgnu
if @samp{-mbaserel} and no @samp{-mshort} and no @samp{-mint}

@item -lbmint16
@itemx -lbgnu16
if @samp{-mbaserel} and @samp{-mshort} and @samp{-mint}

@item -lbmint
@itemx -lbgnu
if @samp{-mbaserel} and no @samp{-mshort} and @samp{-mint}
@end table

  If you have trouble with the correct setup run @samp{gcc -v} and see,
what GCC is trying to do.

@node  Headers, Gulam notes, Libraries, Installing GCC
@comment  node-name,  next,  previous,  up
@section Installing the Header Files
@cindex Header Installation

  The last bit to install are the header files. They are contained in an
archive of their own. The preprocessor now knows about the variable
@code{GNUINC}. Earlier version had to use the @samp{-I@var{prefix}}
option, to get to the header files. According to the above examples, the
files would be put in the directory @file{e:\gnu\include}. @code{GNUINC}
has to be set accordingly.@refill
@cindex GNUINC

  If you like to write programs for MiNT, apart from the libraries you
also need the MiNT specific include files (also from the Atari archive).
These are found in the archive @file{mntinc@var{xx}.zoo} in the
@file{mint} directory. @var{xx} matches the version number of the
library. (@xref{The C-Compiler Driver}, for more info on
compiling programs for MiNT (the @samp{-mint} option)).

  If you choose to have both sets of libraries installed you can keep
the TOS specific header files since they are compatible with the MiNT
ones.

@node     Gulam notes,  , Headers, Installing GCC
@comment  node-name, next, previous, up
@section Gulam Notes
@cindex Gulam Notes

  The programs, which come with the GCC distribution also understand
filenames, which use the slash (@samp{/}) as a separator. When Gulam is
your favorite CLI you will stick to the backslashes, since you otherwise
lose the feature of command line completition.@refill

  If you are using Gulam, you can define @samp{aliases} to reach the
executables under more common names.@refill

@example
alias cc e:\gnu\bin\gcc.ttp
alias ar e:\gnu\bin\gcc-ar.ttp
alias as e:\gnu\bin\gcc-as.ttp
alias ld e:\gnu\bin\gcc-ld.ttp
@dots{}
@end example

  Now you should be able to say @samp{cc foo.c -o foo.ttp} and the
obvious thing should happen. If you still have trouble, compare your
settings with the ones from the sample file @file{gulam.g}. That should
give you the right idea.@refill

  One additional note to Gulam. @file{crt0.o} is currently set up to
understand the MWC/Atari convention of passing long command lines
(except it doesn't look into the @code{_io_vector} part). Gulam users
should set @samp{env_style mw}, if you want to give long args lines to
@file{gcc.ttp}.@refill

  To summarize the above, here are the settings from my @file{gulam.g}
initialization file. The usage of @code{UNIXMODE} environment variable
is explained in the file @file{unixmode.doc}, which is part of the
library sources. The @code{GXXINC} variable is for G++.

@example
set env_style mw
setenv TEMP i:
setenv PATH e:\gnu\bin;<your other search paths here>
setenv GCCEXEC e:\gnu\bin\gcc-
setenv GNULIB e:\gnu\lib
setenv GNUINC e:\gnu\include
setenv GXXINC e:\gnu\g++-inc
setenv UNIXMODE 'd/brG'
@end example
@page

@node  Installing Gxx, Memory Requirements, Installing GCC, Top
@comment  node-name,     next,  	      previous,       up
@chapter Installing G++
@cindex Installing G++
@cindex G++ Installation

  For the G++ installation apply the same rules as for the GCC
installation. The G++ compiler driver @file{g++.ttp} and the actual
compiler @file{gcc-cc1+.ttp} belong into the same directory as the GCC
executables. The preprocessor is shared between G++ and GCC. The library
@file{g++.olb} goes into the same directory as all the other libraries.
Since G++ has a complete set of include files of it's own, they all
should be copied into the directory @file{\gnu\g++-inc}. To let the
preprocessor know, where it can find the include files, the variable
@code{GXXINC} is used.@refill
@cindex GXXINC (env. variable)

  The above is valid for G++ 1.xx. Since GCC and G++ were merge into one
large package with version 2.x, there is no longer a special compiler
driver for G++. @file{gcc.ttp} determines from the file extension, whether
the C or C++ compiler should be invoked. The file @file{gcc-cc1plus.ttp}
is the actual C++ compiler. This file name is usually truncated to
@file{gcc-cc1p.ttp} in the 8+3 TOS file system. What is said about the
include files and the variable @code{GXXINC} is also true for G++ 2.x.

  To actually use G++, some requirements have to be fulfilled. You need
the GCC include files and libraries with at least patch level 72.
Additionally the linker @file{gcc-ld.ttp} must have at least patch level
22.

  The library @file{g++.olb} is at the moment not 100% 16bit clean. That
means, there is at the moment no version, which is compiled with the
@samp{-mshort} option.
@page

@node     Memory Requirements, The C-Compiler Driver, Installing Gxx, Top
@comment  node-name,           next,                previous,       up
@chapter Memory Requirements
@cindex Memory Requirements
@cindex Requirements, Memory

  GCC loves memory. A lot. It loves to cons structures. Lots of them.
Earlier versions probably won't run at all in less than 1 Meg; the
version 1.36 of GCC will probably need 2 Meg. The @file{gcc-cc1.ttp} had
1/2 meg stack, and needs it for compiling large files with optimization
turned on. Happily, it doesn't need all that stack for smaller files, or
even big files without the @samp{-O} option, so it should be feasible to
make a compiler with a smaller stack (with @file{fixstk.ttp}).@refill

  GCC versions 1.37 and later uses another scheme for memory allocation.
The programs @file{gcc-cpp.ttp} and @file{gcc-cc1.ttp} are setup for
@code{_stksize == -1L}. This means, that an executable will use all
available memory, doing mallocs from internal heap (as opposed to the
system heap via @code{Malloc}), with @code{SP} initially set at the top,
and heap starting just above the @code{BSS}. So if the compiler runs out
of memory, you probably need more memory (or get rid of accessories,
tsr's etc and try).@refill

  During my compilation of @TeX{} 3.1 on my ST, I found that the size of
a source file is not main the limiting factor, but the size of a
function. At that time my ST was equipped with 2.5 megs of memory. About
512 Kb was used for ramdisk, cache and some auto folder programs. With
this configuration the maximum size of a function, which could be
compiled, was about 14-20 KB depending on how much code was inlined.
Additionally I was able to compile GCC 1.40 and GAS 1.38 on my ST, but
for this I had to disable nearly every program in the auto folder. So,
with GCC 1.40 you're doing fine with 2 or 2,5 Mb.

  With GCC 2.2 and later you definitly need more memory. The compiler
executable itself is about 850 Kb in size. The C++ compiler is even
larger (about 1.1 Mb). So, with GCC 2 you should have atleast 4 Mb.

  The above described scheme, how GCC allocates memory from the heap is
not so nice in a multitasking environment (MiNT or MultiTOS). Once the
comiler has grabed all the available memory, it is practically
impossible to start another process. You can the improve the situation
by changeing the value of @code{_stksize}, when you compile under MiNT.
You can set @code{_stksize} for @file{gcc-cc1.ttp} to approx 350 - 512
Kb.  This gives the compiler enough stack space to run comfortably. For
the preprocessor the situation is slightly more complicated. Since
@file{gcc-cpp.ttp} allocates nearly all memory through the routine
@code{alloca()}, which in turn allocates it's memory from the stack, you
have to set @code{_stksize} to a pretty high value. The value directly
corresponds to size of the source file, you want to preproccess, since
the whole file is slurped into memory and then processed. In my opinion
a good rule of thumb would be to multiply the size of the largest file
you want to compile by 2 or 2.5 and set @code{_stksize} to this value.

  Below is a snapshot from my system (SST68030 with 8MB), while
compiling the file @file{makeinfo.c} from the Texinfo 2.16 distribution.
This file has a size of about 207Kb. @samp{_stksize} of
@file{gcc-cc1.ttp} is set to 512 Kb. The preprocessor (@samp{_stksize}
set to 768Kb) used about 1.5 Mb of memory.

@example
PID PPID STATUS   SIZE  COMMAND
... ... ....
000 000 Wait    724480  (idle)
002 000 Wait      1024  GEM
003 002 Run     557056  GEM
005 000 Sleep   359936  TCSH
149 000 Sleep  1557760  EMACS
150 149 Sleep    29184  wakeup 60
158 149 Wait     99072  sh -c gmake -f makefile.st CC=gcc makeinfo
159 158 Wait    175616  gmake -f makefile.st CC=gcc makeinfo.o
160 159 Wait     69632  gcc -c -O2 -Wall -DDOTS -fomit-frame-point
161 005 Run      78336  top
163 160 Run    1981184  gcc-cc1 c:/clipbr/cc1600.i -quiet -dumpbas
@end example

  Another topic, which frequently comes up on comp.sys.atari.st and
which also loosely fits into this section is "Why are GCC compiled
binaries so big". The reason is simply maximum U**x compatiblity and
@emph{not} bad code quality. There is quite a bit of code in the
libraries, which emulates certain U**x features, which are alway
automatically linked into the executable. Apart from other minor
compatiblity functions, the features, which implement most of the
overhead, are the @code{signal()} emulation and the functionality of the
extended file system, directed through the @code{UNIXMODE} environment
variable.

  The extended filesystem in the TOS libraries is a layer in between the
@code{open()} and all the other file descriptor based i/o routines and
the actual systemcalls in the TOS kernel (@code{fopen()},
@code{fwrite()}, etc.). This extended file system allows file names with
upto 32 characters and symbolic links. The just mentioned layer takes
care of the mapping from the long to a unique file name in the standard
8+3 TOS file system, by maintaining an additional file (@file{.dir}),
which holds the mapping from long to short name. The setting of the
@code{UNIXMODE} environment variable determines, which of the available
features in extended file system layer are used at runtime.

@example
@group
user land        +----------------+
  -+-            | Long file name |
   ^             +----------------+
   |                     |
   |                     V
   |             +----------------+
                 | STDIO fopen()  |
   L             +----------------+
   i                     |
   b                     V
   r             +----------------+
   a             |    open()      |
   r             +----------------+
   y                     |
                         V
   |          +--------------------------+
   |          |extended file system layer|-->-+
   |          +--------------------------+    |
   |                     |                    |
  -+-                    V                    |
                 +----------------+           |
kernel land      |  TOS fopen()   |           |
                 +----------------+           |
                         |                    |
                         V                    V
                 +----------------+        +------+
TOS file system  | 8+3 file name  |        | .dir |
                 +----------------+        +------+
@end group
@end example

  Now, with that in mind you will probably understand, why executables,
which are linked with the TOS libs are so much bigger compared to
executables from other Atari compilers. All this compatility stuff adds
up. What you get for this increased executable size is maximum U**x
compatiblity. You often have to change only a hand full of lines to
succesfully compile a source file from an U**x environment.

  If you know a bit about operating systems in general, you will know,
that stuff like the above doesn't belong into a library into the hands
of a user. This stuff belongs into the kernel. All this is implemented
in the MiNT kernel (through the loadable file system). The executables,
which are linked with the MiNT libs are therefore smaller, than their
TOS equivalents, since a lot of compatibily hacks are no longer present. 
@page

@node The C-Compiler Driver, The Cxx-Compiler Driver, Memory Requirements, Top
@comment  node-name,           next,             previous,            up
@chapter Controlling the C-Compiler Driver (@file{gcc.ttp})
@cindex C-Compiler Driver
@cindex gcc.ttp (executable)

  The GNU C compiler uses a command syntax much like the U**x C
compiler. The @file{gcc.ttp} program accepts options and file names as
operands.  Multiple single-letter options may @emph{not} be grouped:
@samp{-dr} is very different from @samp{-d -r}.

  When you invoke GNU CC, it normally does preprocessing, compilation,
assembly and linking. File names which end in @samp{.c} are taken as C
source to be preprocessed and compiled; file names ending in @samp{.i}
are taken as preprocessor output to be compiled; compiler output files
plus any input files with names ending in @samp{.s} are assembled; then
the resulting object files, plus any other input files, are linked
together to produce an executable.

  Command options allow you to stop this process at an intermediate
stage.

  For example, the @samp{-c} option says not to run the linker. Then the
output consists of object files output by the assembler.

  Other command options are passed on to one stage of processing. Some
options control the preprocessor and others the compiler itself. Yet
other options control the assembler and linker; these are not documented
here, but you rarely need to use any of them.

  Here are the options to control the overall compilation process,
including those that say whether to link, whether to assemble, and so
on.

@cindex Invoking the Compiler Driver
@table @samp
@cindex Options (gcc)
@item -o @var{file}
@findex o (gcc, g++)
Place output in file @var{file}. This applies regardless to whatever
sort of output is being produced, whether it be an executable file,
an object file, an assembler file or preprocessed C code.

If @samp{-o} is not specified, the default is to put an executable file
in @file{a.out}, the object file @file{@var{source}.c} in
@file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and
preprocessed C on standard output.@refill

@item -c
@findex c (gcc)
Compile or assemble the source files, but do not link. Produce object
files with names made by replacing @samp{.c} or @samp{.s} with
@samp{.o} at the end of the input file names. Do nothing at all for
object files specified as input.

@item -S
@findex S (gcc, g++)
Compile into assembler code but do not assemble. The assembler output
file name is made by replacing @samp{.c} with @samp{.s} at the end of
the input file name.  Do nothing at all for assembler source files or
object files specified as input.

@item -E
@findex E (gcc, g++)
Run only the C preprocessor. Preprocess all the C source files
specified and output the results to standard output.

@item -v
@findex v (gcc, g++)
Compiler driver program prints the commands it executes as it runs
the preprocessor, compiler proper, assembler and linker. Some of
these are directed to print their own version numbers.

@item -s
@findex s (gcc, g++)
The executable is stripped from the DRI compatible or extended symbol
table. Certain symbolic debuggers like @file{sid.prg} work with this
symbol table. Also the programs @file{printstk.ttp} and
@file{fixstk.ttp} (See @xref{The Utilities}, for more info) lookup the
symbol @samp{_stksize} in this table.

@item -x
@findex x (gcc, g++)
This option directs the linker to discard all local labels while
creating the symbol table and write only those labels, which are marked
global.

@item -G
@findex G (gcc, g++)
Instead of the standard DRI compatible symbol table, an extended symbol
table is written, which allows symbol names to be up to 22 characters
long. Most of the utility programs have been updated to work with this
format. The most benefit you get with @file{gprof.ttp} and @file{adb}
(the adb-like debugger, originally written for the Sozobon C compiler by
Johann Rueg and Don Dugger and later improved by Michal Jaegermann
(See @xref{Debugging}, for additional info about debugging)).

@item -B@var{prefix}
@findex B (gcc, g++)
The compiler driver program tries @var{prefix} as a prefix for each
program it tries to run. These programs are @file{gcc-cpp.ttp},
@file{gcc-cc1.ttp}, @file{gcc-as.ttp} and @file{gcc-ld.ttp}.

For each subprogram to be run, the compiler driver first tries the
@samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
was not specified, the driver tries two standard prefixes, which are
@file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}. If neither of
those results in a file name that is found, the unmodified program
name is searched for using the directories specified in your
@samp{PATH} environment variable.@refill

You can get a similar result from the environment variable
@code{GCCEXEC}. If it is defined, its value is used as a prefix in the
same way. If both the @samp{-B} option and the @code{GCCEXEC} variable
are present, the @samp{-B} option is used first and the environment
variable value second.@refill

@item -z
@findex z (gcc, g++)
@cindex compile.err
This option directs all output from @samp{stderr} to the file
@file{compile.err}. So, all error messages and warnings, which are
printed during a compile run are written to this file. The redirection
is done by the compiler driver and is therefore only valid for those
programs, which are subsequently invoked by @file{gcc.ttp}. The
@samp{-z} option was introduced only very lately, so not every
executable floating around might have it.@refill
@end table

  These options control the details of C compilation itself.

@table @samp
@item -ansi
@findex ansi (gcc)
Support all ANSI standard C programs.

This turns off certain features of GNU C that are incompatible with
ANSI C, such as the @code{asm}, @code{inline} and @code{typeof}
keywords, and predefined macros such as @code{unix} and @code{vax}
that identify the type of system you are using. It also enables the
undesirable and rarely used ANSI trigraph feature.@refill

The @samp{-ansi} option does not cause non-ANSI programs to be
rejected gratuitously. For that, @samp{-pedantic} is required in
addition to @samp{-ansi}.

The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
option is used.  Some header files may notice this macro and refrain
from declaring certain functions or defining certain macros that the
ANSI standard doesn't call for; this is to avoid interfering with
any programs that might use these names for other things.

@item -traditional
@findex traditional (gcc)
Attempt to support some aspects of traditional C compilers.
Specifically:

@itemize @bullet
@item
All @code{extern} declarations take effect globally even if they
are written inside of a function definition.  This includes implicit
declarations of functions.

@item
The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
and @code{volatile} are not recognized.@refill

@item
Comparisons between pointers and integers are always allowed.

@item
Integer types @code{unsigned short} and @code{unsigned char} promote
to @code{unsigned int}.

@item
Out-of-range floating point literals are not an error.

@item
All automatic variables not declared @code{register} are preserved by
@code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
not declared @code{volatile} may be clobbered.

@item
In the preprocessor, comments convert to nothing at all, rather than
to a space. This allows traditional token concatenation.

@item
In the preprocessor, macro arguments are recognized within string
constants in a macro definition (and their values are stringified,
though without additional quote marks, when they appear in such a
context). The preprocessor always considers a string constant to end
at a newline.

@item
The predefined macro @code{__STDC__} is not defined when you use
@samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
which @code{__GNUC__} indicates are not affected by
@samp{-traditional}).  If you need to write header files that work
differently depending on whether @samp{-traditional} is in use, by
testing both of these predefined macros you can distinguish four
situations: GNU C, traditional GNU C, other ANSI C compilers, and
other old C compilers.
@end itemize

@item -O
@findex O (gcc, g++)
Optimize. Optimizing compilation takes somewhat more time, and a lot
more memory for a large function.
Without @samp{-O}, the compiler's goal is to reduce the cost of
compilation and to make debugging produce the expected results.
Statements are independent: if you stop the program with a breakpoint
between statements, you can then assign a new value to any variable or
change the program counter to any other statement in the function and
get exactly the results you would expect from the source code.

Without @samp{-O}, only variables declared @code{register} are
allocated in registers. The resulting compiled code is a little worse
than produced by PCC without @samp{-O}.

With @samp{-O}, the compiler tries to reduce code size and execution
time.Some of the @samp{-f} options described below turn specific kinds of
optimization on or off.

@item -g
@findex g (gcc, g++)
Produce debugging information in the operating system's native format
(for DBX or SDB). GCC on the Atari produces the DBX debugging format.
GDB also works with this debugging information.

Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
@samp{-O}. The shortcuts taken by optimized code may occasionally
produce surprising results: some variables you declared may not exist
at all; flow of control may briefly move where you did not expect it;
some statements may not be executed because they compute constant
results or their values were already at hand; some statements may
execute in different places because they were moved out of loops.
Nevertheless it proves possible to debug optimized output. This makes
it reasonable to use the optimizer for programs that might have bugs.

@item -gg
@findex gg (gcc, g++)
Produce debugging information in GDB's own format. This option is no
longer supported. Do not use it.

@item -w
@findex w (gcc, g++)
Inhibit all warning messages.

@item -W
@findex W (gcc, g++)
Print extra warning messages for these events:

@itemize @bullet
@item
An automatic variable is used without first being initialized.

These warnings are possible only in optimizing compilation,
because they require data flow information that is computed only
when optimizing.  They occur only for variables that are
candidates for register allocation.  Therefore, they do not occur
for a variable that is declared @code{volatile}, or whose address
is taken, or whose size is other than 1, 2, 4 or 8 bytes.  Also,
they do not occur for structures, unions or arrays, even when
they are in registers.

Note that there may be no warning about a variable that is used
only to compute a value that itself is never used, because such
computations may be deleted by the flow analysis pass before the
warnings are printed.

These warnings are made optional because GNU CC is not smart
enough to see all the reasons why the code might be correct
despite appearing to have an error.  Here is one example of how
this can happen:

@example
@{
  int x;
  switch (y)
    @{
    case 1: x = 1;
      break;
    case 2: x = 4;
      break;
    case 3: x = 5;
    @}
  foo (x);
@}
@end example

@noindent
If the value of @code{y} is always 1, 2 or 3, then @code{x} is
always initialized, but GNU CC doesn't know this.  Here is
another common case:

@example
@{
  int save_y;
  if (change_y) save_y = y, y = new_y;
  @dots{}
  if (change_y) y = save_y;
@}
@end example

@noindent
This has no bug because @code{save_y} is used only if it is set.

Some spurious warnings can be avoided if you declare as
@code{volatile} all the functions you use that never return.
@c @xref{Function Attributes}.

@item
A nonvolatile automatic variable might be changed by a call to
@code{longjmp}.  These warnings as well are possible only in
optimizing compilation.

The compiler sees only the calls to @code{setjmp}.  It cannot know
where @code{longjmp} will be called; in fact, a signal handler could
call it at any point in the code.  As a result, you may get a warning
even when there is in fact no problem because @code{longjmp} cannot
in fact be called at the place which would cause a problem.

@item
A function can return either with or without a value.  (Falling
off the end of the function body is considered returning without
a value.)  For example, this function would inspire such a
warning:

@example
foo (a)
@{
  if (a > 0)
    return a;
@}
@end example

Spurious warnings can occur because GNU CC does not realize that
certain functions (including @code{abort} and @code{longjmp})
will never return.

@item
An expression-statement contains no side effects.
@end itemize

In the future, other useful warnings may also be enabled by this
option.

@item -Wimplicit
@findex Wimplicit (gcc, g++)
Warn whenever a function is implicitly declared.

@item -Wreturn-type
@findex Wreturn-type (gcc, g++)
Warn whenever a function is defined with a return-type that defaults
to @code{int}.  Also warn about any @code{return} statement with no
return-value in a function whose return-type is not @code{void}.

@item -Wunused
@findex Wunused (gcc, g++)
Warn whenever a local variable is unused aside from its declaration,
and whenever a function is declared static but never defined.

@item -Wswitch
@findex Wswitsch (gcc, g++)
Warn whenever a @code{switch} statement has an index of enumeral type
and lacks a @code{case} for one or more of the named codes of that
enumeration.  (The presence of a @code{default} label prevents this
warning.)  @code{case} labels outside the enumeration range also
provoke warnings when this option is used.

@item -Wcomment
@findex Wcomment (gcc, g++)
Warn whenever a comment-start sequence @samp{/*} appears in a comment.

@item -Wtrigraphs
@findex Wtrigraphs (gcc, g++)
Warn if any trigraphs are encountered (assuming they are enabled).

@item -Wall
@findex Wall (gcc, g++)
All of the above @samp{-W} options combined.  These are all the
options which pertain to usage that we recommend avoiding and that we
believe is easy to avoid, even in conjunction with macros.

The other @samp{-W@dots{}} options below are not implied by @samp{-Wall}
because certain kinds of useful macros are almost impossible to write
without causing those warnings.

@item -Wshadow
@findex Wshadow (gcc, g++)
Warn whenever a local variable shadows another local variable.

@item -Wid-clash-@var{len}
@findex Wid-clash- (gcc, g++)
Warn whenever two distinct identifiers match in the first @var{len}
characters.  This may help you prepare a program that will compile
with certain obsolete, brain-damaged compilers.

@item -Wpointer-arith
@findex Wpointer-arith (gcc, g++)
Warn about anything that depends on the ``size of'' a function type or
of @code{void}.  GNU C assigns these types a size of 1, for
convenience in calculations with @code{void *} pointers and pointers
to functions.

@item -Wcast-qual
@findex Wcast-qual (gcc, g++)
Warn whenever a pointer is cast so as to remove a type qualifier from
the target type.  For example, warn if a @code{const char *} is cast
to an ordinary @code{char *}.

@item -Wwrite-strings
@findex Wwrite-strings (gcc, g++)
Give string constants the type @code{const char[@var{length}]} so that
copying the address of one into a non-@code{const} @code{char *}
pointer will get a warning.  These warnings will help you find at
compile time code that can try to write into a string constant, but
only if you have been very careful about using @code{const} in
declarations and prototypes.  Otherwise, it will just be a nuisance;
this is why we did not make @samp{-Wall} request these warnings.

@item -p
@findex p (gcc, g++)
Generate extra code to write profile information suitable for the
analysis program @code{prof}. This is useless on the Atari ST. Use
@code{-pg} instead.

@item -pg
@findex pg (gcc, g++)
Generate extra code to write profile information suitable for the
analysis program @code{gprof}.

@item -l@var{library}
@findex l (gcc, g++)
Search a standard list of directories for a library named
@var{library}, which is actually a file named
@file{$GNULIB\@var{library}.olb}. The linker uses this file as if it
had been specified precisely by name.@refill

The directories searched include several standard system directories
plus any that you specify with @samp{-L}.

Normally the files found this way are library files---archive files
whose members are object files.  The linker handles an archive file by
scanning through it for members which define symbols that have so far
been referenced but not defined.  But if the file that is found is an
ordinary object file, it is linked in the usual fashion.  The only
difference between using an @samp{-l} option and specifying a file name
is that @samp{-l} searches several directories.

@item -L@var{dir}
@findex L (gcc, g++)
Add directory @var{dir} to the list of directories to be searched
for @samp{-l}.

@item -nostdlib
@findex nostdlib (gcc, g++)
Don't use the standard system libraries and startup files when
linking. Only the files you specify (plus @file{gnulib}) will be
passed to the linker.

@item -m@var{machinespec}
@findex m (gcc, g++)
Machine-dependent option specifying something about the type of target
machine. These options are defined by the macro
@code{TARGET_SWITCHES} in the machine description. The default for
the options is also defined by that macro, which enables you to change
the defaults.@refill

These are the @samp{-m} options defined in the 68000 machine
description:

@table @samp
@item -m68000
@item -mc68000
@findex m68000 (gcc, g++)
@findex mc68000 (gcc, g++)
Generate output for a 68000. This is the default on the Atari ST.

@item -m68020
@itemx -mc68020
@findex m68020 (gcc, g++)
@findex mc68020 (gcc, g++)
Generate output for a 68020 (rather than a 68000).

@item -m68881
@findex m68881 (gcc, g++)
Generate output containing 68881 instructions for floating point.

@item -msoft-float
@findex msoft-float (gcc, g++)
Generate output containing library calls for floating point.

@item -mshort
@findex mshort (gcc, g++)
Consider type @code{int} to be 16 bits wide, like @code{short int} and
causes the macro @code{__MSHORT__} to be defined. Using this option
also causes the library @file{@var{library}16.olb} to be linked. (Also
@xref{Predefined Macros}, for more info)

@item -mint
@findex mint (gcc, g++)
Compile for MiNT (MiNT is not TOS). The macro @code{__MINT__} is defined
and the linker links with the mint library @samp{-lmint} before linking
with the normal C library @samp{-lgnu}. Also, the linker uses the
startup file @file{mcrt0.o} instead of the normal @file{crt0.o}. If
@samp{-mshort} is also specified, then both the macros @code{__MSHORT__}
and @code{__MINT__} are defined and the linker links with @samp{-lmint16
-lgnu16}.@refill

@item -mbaserel
@findex mbaserel (gcc, g++)

@item -mpcrel
@findex mpcrel (gcc, g++)
This is no op at the moment.

@item -mnobitfield
@findex mnobitfield (gcc, g++)
Do not use the bit-field instructions.  @samp{-m68000} implies
@samp{-mnobitfield}.

@item -mbitfield
@findex mbitfield (gcc, g++)
Do use the bit-field instructions.  @samp{-m68020} implies
@samp{-mbitfield}.  This is the default if you use the unmodified
sources.

@item -mrtd
@findex mrtd (gcc, g++)
Use a different function-calling convention, in which functions
that take a fixed number of arguments return with the @code{rtd}
instruction, which pops their arguments while returning. This
saves one instruction in the caller since there is no need to pop
the arguments there.

This calling convention is incompatible with the one normally
used on U**x, so you cannot use it if you need to call libraries
compiled with the U**x compiler.

Also, you must provide function prototypes for all functions that
take variable numbers of arguments (including @code{printf});
otherwise incorrect code will be generated for calls to those
functions.

In addition, seriously incorrect code will result if you call a
function with too many arguments.  (Normally, extra arguments are
harmlessly ignored.)

The @code{rtd} instruction is supported by the 68010 and 68020
processors, but not by the 68000.
@end table

@item -f@var{flag}
Specify machine-independent flags.  Most flags have both positive and
negative forms; the negative form of @samp{-ffoo} would be
@samp{-fno-foo}.  In the table below, only one of the forms is
listed---the one which is not the default.  You can figure out the
other form by either removing @samp{no-} or adding it.

@table @samp
@item -ffloat-store
@findex ffloat-store (gcc, g++)
Do not store floating-point variables in registers.  This
prevents undesirable excess precision on machines such as the
68000 where the floating registers (of the 68881) keep more
precision than a @code{double} is supposed to have.

For most programs, the excess precision does only good, but a few
programs rely on the precise definition of IEEE floating point.
Use @samp{-ffloat-store} for such programs.

@item -fno-asm
@findex fno-asm (gcc, g++)
Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
keyword.  These words may then be used as identifiers.

@item -fno-defer-pop
@findex fno-defer-pop (gcc, g++)
Always pop the arguments to each function call as soon as that
function returns.  Normally the compiler (when optimizing) lets
arguments accumulate on the stack for several function calls and
pops them all at once.

@item -fstrength-reduce
@findex fstrength-reduce (gcc, g++)
Perform the optimizations of loop strength reduction and
elimination of iteration variables.

@item -fcombine-regs
@findex fcombine-regs (gcc 1.40, g++ 1.40.3)
Allow the combine pass to combine an instruction that copies one
register into another. This might or might not produce better
code when used in addition to @samp{-O}. I am interested in
hearing about the difference this makes. (Only GCC and G++ 1.40).

@item -fforce-mem
@findex fforce-mem (gcc, g++)
Force memory operands to be copied into registers before doing
arithmetic on them.  This may produce better code by making all
memory references potential common subexpressions.  When they are
not common subexpressions, instruction combination should
eliminate the separate register-load.  I am interested in hearing
about the difference this makes.

@item -fforce-addr
@findex fforce-addr (gcc, g++)
Force memory address constants to be copied into registers before
doing arithmetic on them. This may produce better code just as
@samp{-fforce-mem} may.

@item -fomit-frame-pointer
@findex fomit-frame-pointer (gcc, g++)
Don't keep the frame pointer in a register for functions that
don't need one.  This avoids the instructions to save, set up and
restore frame pointers; it also makes an extra register available
in many functions. @strong{It also makes debugging impossible.}

On some machines, such as the Vax, this flag has no effect,
because the standard calling sequence automatically handles the
frame pointer and nothing is saved by pretending it doesn't
exist.  The machine-description macro
@code{FRAME_POINTER_REQUIRED} controls whether a target machine
supports this flag.@refill
@c @xref{Registers}.@refill

@item -finline-functions
@findex finline-functions (gcc, g++)
Integrate all simple functions into their callers. The compiler
heuristically decides which functions are simple enough to be
worth integrating in this way.

If all calls to a given function are integrated, and the function
is declared @code{static}, then the function is normally not
output as assembler code in its own right.

@item -fcaller-saves
@findex fcaller-saves (gcc, g++)
Enable values to be allocated in registers that will be clobbered by
function calls, by emitting extra instructions to save and restore the
registers around such calls.  Such allocation is done only when it
seems to result in better code than would otherwise be produced.

This option is enabled by default on certain machines, usually those
which have no call-preserved registers to use instead.

@item -fkeep-inline-functions
@findex fkeep-inline-functions (gcc, g++)
Even if all calls to a given function are integrated, and the
function is declared @code{static}, nevertheless output a
separate run-time callable version of the function.

@item -fwritable-strings
@findex fwritable-strings (gcc, g++)
Store string constants in the writable data segment and don't
uniquize them.  This is for compatibility with old programs which
assume they can write into string constants. Writing into string
constants is a very bad idea; ``constants'' should be constant.

@item -fcond-mismatch
@findex fcond-mismatch (gcc, g++)
Allow conditional expressions with mismatched types in the second and
third arguments. The value of such an expression is void.

@item -fno-function-cse
@findex fno-function-cse (gcc, g++)
Do not put function addresses in registers; make each instruction
that calls a constant function contain the function's address
explicitly.

This option results in less efficient code, but some strange
hacks that alter the assembler output may be confused by the
optimizations performed when this option is not used.

@item -fvolatile
@findex fvolatile (gcc, g++)
Consider all memory references through pointers to be volatile.

@item -fshared-data
@findex fshared-data (gcc, g++)
Requests that the data and non-@code{const} variables of this
compilation be shared data rather than private data.  The distinction
makes sense only on certain operating systems, where shared data is
shared between processes running the same program, while private data
exists in one copy per process.

@item -funsigned-char
@findex funsigned-char (gcc, g++)
Let the type @code{char} be the unsigned, like @code{unsigned char}.

Each kind of machine has a default for what @code{char} should
be. It is either like @code{unsigned char} by default or like
@code{signed char} by default.  (Actually, at present, the
default is always signed.)

The type @code{char} is always a distinct type from either
@code{signed char} or @code{unsigned char}, even though its
behavior is always just like one of those two.

Note that this is equivalent to @samp{-fno-signed-char}, which is the
negative form of @samp{-fsigned-char}.

@item -fsigned-char
@findex fsigned-char (gcc, g++)
Let the type @code{char} be signed, like @code{signed char}.

Note that this is equivalent to @samp{-fno-unsigned-char}, which is
the negative form of @samp{-funsigned-char}.

@item -ffixed-@var{reg}
@findex ffixed- (gcc, g++)
Treat the register named @var{reg} as a fixed register; generated
code should never refer to it (except perhaps as a stack pointer,
frame pointer or in some other fixed role).

@var{reg} must be the name of a register. The register names
accepted are machine-specific and are defined in the
@code{REGISTER_NAMES} macro in the machine description macro
file.

This flag does not have a negative form, because it specifies a
three-way choice.

@item -fcall-used-@var{reg}
@findex fcall-used- (gcc, g++)
Treat the register named @var{reg} as an allocatable register
that is clobbered by function calls.  It may be allocated for
temporaries or variables that do not live across a call.
Functions compiled this way will not save and restore the
register @var{reg}.

Use of this flag for a register that has a fixed pervasive role
in the machine's execution model, such as the stack pointer or
frame pointer, will produce disastrous results.

This flag does not have a negative form, because it specifies a
three-way choice.

@item -fcall-saved-@var{reg}
@findex fcall-saved- (gcc, g++)
Treat the register named @var{reg} as an allocatable register
saved by functions. It may be allocated even for temporaries or
variables that live across a call. Functions compiled this way
will save and restore the register @var{reg} if they use it.

Use of this flag for a register that has a fixed pervasive role
in the machine's execution model, such as the stack pointer or
frame pointer, will produce disastrous results.

A different sort of disaster will result from the use of this
flag for a register in which function values may be returned.

This flag does not have a negative form, because it specifies a
three-way choice.
@end table

@item -pedantic
@findex pedantic (gcc)
Issue all the warnings demanded by strict ANSI standard C; reject
all programs that use forbidden extensions.

Valid ANSI standard C programs should compile properly with or without
this option (though a rare few will require @samp{-ansi}). However,
without this option, certain GNU extensions and traditional C features
are supported as well. With this option, they are rejected. There is
no reason to @i{use} this option; it exists only to satisfy pedants.
@end table

These options control the C preprocessor, which is run on each C source
file before actual compilation. If you use the @samp{-E} option, nothing
is done except C preprocessing. Some of these options make sense only
together with @samp{-E} because they request preprocessor output that is
not suitable for actual compilation.

@table @samp
@item -C
@findex C (gcc, g++)
Tell the preprocessor not to discard comments. Used with the
@samp{-E} option.

@item -I@var{dir}
@findex I (gcc, g++)
Search directory @var{dir} for include files.

@item -I-
Any directories specified with @samp{-I} options before the @samp{-I-}
option are searched only for the case of @samp{#include "@var{file}"};
they are not searched for @samp{#include <@var{file}>}.

If additional directories are specified with @samp{-I} options after
the @samp{-I-}, these directories are searched for all @samp{#include}
directives. (Ordinarily @emph{all} @samp{-I} directories are used
this way.)

In addition, the @samp{-I-} option inhibits the use of the current
directory as the first search directory for @samp{#include
"@var{file}"}. Therefore, the current directory is searched only if
it is requested explicitly with @samp{-I.}. Specifying both
@samp{-I-} and @samp{-I.} allows you to control precisely which
directories are searched before the current one and which are searched
after.@refill

@item -nostdinc
@findex nostdinc (gcc, g++)
Do not search the standard system directories for header files.  Only
the directories you have specified with @samp{-I} options (and the
current directory, if appropriate) are searched.

Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all
directories from the search path except those you specify.

@item -M
@findex M (gcc, g++)
Tell the preprocessor to output a rule suitable for @code{make}
describing the dependencies of each source file.  For each source
file, the preprocessor outputs one @code{make}-rule whose target is
the object file name for that source file and whose dependencies are
all the files @samp{#include}d in it. This rule may be a single line
or may be continued with @samp{\}-newline if it is long.

@samp{-M} implies @samp{-E}.

@item -MM
@findex MM (gcc, g++)
Like @samp{-M} but the output mentions only the user-header files
included with @samp{#include "@var{file}"}. System header files
included with @samp{#include <@var{file}>} are omitted.

@samp{-MM} implies @samp{-E}.

@item -D@var{macro}
@findex D (gcc, g++)
Define macro @var{macro} with the empty string as its definition.

@item -D@var{macro}=@var{defn}
Define macro @var{macro} as @var{defn}.

@item -U@var{macro}
@findex U (gcc, g++)
Undefine macro @var{macro}.

@item -T
@findex T (gcc, g++)
Support ANSI C trigraphs. You don't want to know about this
brain-damage. The @samp{-ansi} option also has this effect.
@end table
@page

@node The Cxx-Compiler Driver, The Preprocessor, The C-Compiler Driver, Top
@comment  node-name,  next,  previous,  up
@chapter Controlling the C++-Compiler Driver (@file{g++.ttp})
@cindex C++-Compiler Driver
@cindex g++.ttp (executable)

  The GNU C++ compiler uses a command syntax much like the AT&T C++
compiler. The @code{g++.ttp} program accepts options and file names as
operands.  Multiple single-letter options may @emph{not} be grouped:
@samp{-dr} is very different from @samp{-d -r}.

When you invoke GNU C++, it normally does preprocessing, compilation,
assembly and linking.  File names which end in @samp{.c}, @samp{.cc}, or
@samp{.C} are taken as GNU C++ source to be preprocessed and compiled;
compiler output files plus any input files with names ending in
@samp{.s} are assembled; then the resulting object files, plus any other
input files, are linked together to produce an executable.

Unlike C++, there is no @samp{-F} option.  This is because GNU C++ is a
native-code C++ compiler, not a front-end pre-processor.  The advantages
of this organization are faster compilation speed, better
error-reporting capabilities, better opportunity for compiler
optimization, and true source-level debuggability with the GDB debugger
(version 3.4 or higher).

Command options allow you to stop this process at an intermediate stage.
For example, the @samp{-c} option says not to run the linker.  Then the
output consists of object files output by the assembler.

Other command options are passed on to one stage.  Some options control
the preprocessor and others the compiler itself.  Yet other options
control the assembler and linker; these are not documented here because
the GNU assembler and linker are not yet released.

Here are the options to control the overall compilation process, including
those that say whether to link, whether to assemble, and so on. The
options, which don't have any text, behave exactly as their GCC
counterparts.

With GCC 2.x there is no independend compiler driver for C++.
@file{gcc.ttp} handles both cases. One major difference between
@file{g++.ttp} from version 1.xx and @file{gcc.ttp} from version 2.x is,
that you have to explicitly link with @file{g++.olb}. Therefore when you
compile C++ programs with GCC 2.x you alway have to include @code{-lg++}
on the command line, when you create the final executable.

@table @samp
@item -o @var{file}

@item -c
@findex c (g++)

It is intended that the compiler driver of GNU C++ will invoke the
appropriate translator (or series of translators) for a given source file.
Currently, the translators are selected on the basis of their file
extension.  So that one driver can be used for many different translators,
it is important that these extensions be distinct.  It is strongly
suggested that users become accustomed to using a @samp{.cc} file extension
for GNU C++ code, to distinguish it from the @samp{.c} file extension
already used for GNU CC code.

@item -S

@item -E

@item -v

@item -s

@item -x

@item -G
@end table

These options control the details of GNU C++ compilation itself.

@table @samp
@item -ansi
@findex ansi (g++)

With this option enabled, differences between GNU C++ and AT&T C++ are
also flagged.  Because the C++ language definition and the ANSI draft
differ on the interpretation of syntactically identical constructs, it is
unlikely that this flag could possibly be of any real use.  (For this
reason, this flag is currently not fully implemented).

@item -traditional
@findex traditional (g++)

@itemize @bullet
@item
The other aspects of @samp{-traditional} are equivalent to GCC.

@item
The predefined macro @code{__cplusplus} is defined to identify
compilation for C++ 2.0.  C++ version 1.2 uses @code{c_plusplus} as its
identifying macro.  Since GNU C++ implements version 2.0 semantics, the
former is defined, while the latter is not.  The macro @code{__GNUG__}
is also defined, so that features specific to GNU C++ can be used
conditionally.
@end itemize

@item -O

@item -g

@item -w

@item -W

@item -Wimplicit

@item -Wreturn-type

@item -Wunused

@item -Wswitch

@item -Wcomment

@item -Wtrigraphs

@item -Wall

@item -Wshadow

@item -Wid-clash-@var{len}

@item -Wpointer-arith

@item -Wcast-qual

@item -Wwrite-strings

@item -p

@item -pg

@item -l@var{library}

@item -L@var{dir}

@item -nostdlib

@item -m@var{machinespec}

@table @samp
@item -m68020
@itemx -mc68020

@item -m68000
@item -mc68000

@item -m68881

@item -msoft-float

@item -mshort

@item -mint

@item -mnobitfield

@item -mbitfield

@item -mrtd
@end table

@item -f@var{flag}

@table @samp
@item -ffloat-store

@item -fno-asm

@item -fno-defer-pop

@item -fstrength-reduce

@item -fcombine-regs

@item -fforce-mem

@item -fforce-addr

@item -fomit-frame-pointer

@item -finline-functions

@item -fdefault-inline
@findex fdefault-inline (g++)
If this option is enabled then member functions defined inside class
scope are compiled inline by default, @emph{i.e.,} you don't need to
add @var{inline} in front of the member function name.  By popular
demand, this option is now the default.  To keep GNU C++ from inlining
these member functions, specify @code{-fno-default-inline}.

@item -fcaller-saves

@item -fkeep-inline-functions

@item -fwritable-strings

@item -fcond-mismatch

@item -fno-function-cse

@item -fvolatile

@item -fshared-data

@item -funsigned-char

@item -fsigned-char

@item -ffixed-@var{reg}

@item -fcall-used-@var{reg}

@item -fcall-saved-@var{reg}
@end table

@item -fstrict-prototype
@findex fstrict-prototype (g++)
Consider the declaration @code{int foo ();}.  In C++, this means that the
function @code{foo} takes no arguments.  In ANSI C, this is declared
@code{int foo(void);}.  With the flag @samp{-fno-strict-prototype},
declaring functions with no arguments is equivalent to declaring its
argument list to be untyped, i.e., @code{int foo ();} is equivalent to
saying @code{int foo (...);}.

@item -felide-constructors
@findex felide-constructors (g++)
Using this option instructs the compiler to be smarter about when it can
elide constructors.  With out this flag, GNU C++ and cfront both
generate effectively the same code for:

@example
A foo ();
A x (foo ());   // x is initialized by `foo ()', no ctor called here
A y = foo ();   // call to `foo ()' heads to temporary,
                // y is initialized from the temporary.
@end example

Note the difference!  With this flag, GNU C++ initializes `y' directly
from the call to `foo ()' without going through a temporary.

@item -fall-virtual
@findex fall-virtual
When the @samp{-fall-virtual} option is used, all member functions
(except for constructor functions and new/delete member operators)
declared in the same class with a ``method-call'' operator method have
entries made for them in the vtable for the given class.  In effect, all
of these methods become ``implicitly virtual.''

This does @emph{not} mean that all calls to these methods will be made
through the vtable.  There are some circumstances under which it is
obvious that a call to a given virtual function can be made directly,
and in these cases the calls still go direct.

The effect of making all methods of a class with a declared
`operator->()()' implicitly virtual using @samp{-fall-virtual} extends
also to all non-constructor methods of any class derived from such a
class.

@item -fthis-is-variable
@findex fthis-is-variable (g++)
The incorporation of user-defined free store management into C++ has
made assignment to @var{this} an anachronism.  Therefore, by default GNU
C++ treats the type of @var{this} in a member function of @var{class X}
to be @var{X *const}.  In other words, it is illegal to assign to
@var{this} within a class member function.  However, for backwards
compatibility, you can invoke the old behavior by using
@samp{-fthis-is-variable}.

@item -fsave-memoized
@item -fmemoize-lookups
@findex fsave-memoized (g++)
@findex fmemoize-lookups (g++)
These flags are of use to get the compiler to compile programs faster
using heuristics.  They are not on by default since they only do so
about half the time.  They other half of the time programs compile more
slowly (and take more memory).

The first time the compiler must build a call to a member function (or
reference to a data member), it must (1) determine whether the class
implements member functions of that name (2) resolve which member
function to call (which involves figuring out what sorts of type
conversions need to be made), and (3) check the visibility of the member
function to the caller.  All of this adds up to slower compilation.
Normally, the second time a call is made to that member function (or
reference to that data member), it must go through the same lengthy
process again.  This means that code like this

@example
  cout << "This " << p << " has " << n << " legs.\n";
@end example

@noindent
makes six passes through all three steps.  By using a software cache,
a ``hit'' significantly reduces this cost.  Unfortunately, using the
cache introduces another layer of mechanisms which must be implemented,
and so incurrs its own overhead.  The @samp{-fmemoize-lookups} enables
the software cache.

Because access privileges (visibility) to members and member functions
may differ from one function context to the next, may need to be
flushed.  With the @samp{-fmemoize-lookups} flag, the cache is flushed
after every function that is compiled.  With the @samp{-fsave-memoized}
flag, when the compiler determines that the context of the last function
compiled would yield the same access privileges of the next function to
compile, it preserves the cache.  This really helps when defining many
member functions for the same class: with the exception of member
functions which are friends of other classes, each member function has
exactly the same access privileges as every other, and the cache need
not be flushed.

@item -pedantic
Attempt to support strict ANSI standard C.  Since C++ invalidates a number
of ANSI constructions, this switch is of dubious value.  Some attempt has
been made to warn about non-standard C++ features, however, even this is of
uncertain value, as there are two C++ standards currently in
existence: the standard as documented by AT&T, and the standard as
implemented by the AT&T C++ compiler.  Valid C++ programs should compile
properly with or without this switch.  However, without this switch,
certain useful or traditional constructs banned by the standard are
supported.  With this switch, they are rejected.  There is no reason to use
this switch; it exists only to satisfy curious pedants.
@end table

The options, which control the behaviour of the C preprocessor are the
same as for GCC (@xref{The C-Compiler Driver}, last section).
@page

@node    The Preprocessor, The Assembler, The Cxx-Compiler Driver, Top
@comment node-name,        next,          previous,            up
@chapter The Preprocessor
@cindex Preprocessor
@cindex gcc-cpp.ttp (executable)

@ifinfo
Most often when you use the C preprocessor you will not have to invoke
it explicitly: the C compiler will do so automatically. However, the
preprocessor is sometimes useful individually.
@end ifinfo

@menu
* Invoking CPP::        Command options supported by @samp{gcc-cpp.ttp}.
* Predefined Macros::   List of predefined macros
@end menu

@node     Invoking CPP, Predefined Macros, The Preprocessor, The Preprocessor
@comment  node-name,    next,              previous,         up
@section Invoking the C Preprocessor
@cindex Invoking the C Preprocessor

Most often when you use the C preprocessor you will not have to invoke it
explicitly: the C compiler will do so automatically.  However, the
preprocessor is sometimes useful individually.

The C preprocessor expects two file names as arguments, @var{infile} and
@var{outfile}. The preprocessor reads @var{infile} together with any other
files it specifies with @samp{#include}.  All the output generated by the
combined input files is written in @var{outfile}.

Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile}
means to read from standard input and as @var{outfile} means to write to
standard output.  Also, if @var{outfile} or both file names are omitted,
the standard output and standard input are used for the omitted file names.

Here is a table of command options accepted by the C preprocessor.  Most
of them can also be given when compiling a C program; they are passed along
automatically to the preprocessor when it is invoked by the compiler.

@table @samp
@cindex Options (cpp)
@item -P
@findex P (cpp)
Inhibit generation of @samp{#}-lines with line-number information in the
output from the preprocessor. This might be useful when running the
preprocessor on something that is not C code and will be sent to a
program which might be confused by the @samp{#}-lines

@item -C
@findex C (cpp)
Do not discard comments: pass them through to the output file.
Comments appearing in arguments of a macro call will be copied to the
output before the expansion of the macro call.

@item -T
@findex T (cpp)
Process ANSI standard trigraph sequences.  These are three-character
sequences, all starting with @samp{??}, that are defined by ANSI C to
stand for single characters.  For example, @samp{??/} stands for
@samp{\}, so @samp{'??/n'} is a character constant for Newline.
Strictly speaking, the GNU C preprocessor does not support all
programs in ANSI Standard C unless @samp{-T} is used, but if you
ever notice the difference it will be with relief.

You don't want to know any more about trigraphs.

@item -pedantic
@findex pedantic (cpp)
Issue warnings required by the ANSI C standard in certain cases such
as when text other than a comment follows @samp{#else} or @samp{#endif}.

@ifset gcc2
@item -pedantic-errors
@findex pedantic-errors (cpp)
Like @samp{-pedantic}, except that errors are produced rather than
warnings.

@item -Wtrigraphs
@findex Wtrigraphs (cpp)
Warn if any trigraphs are encountered (assuming they are enabled).

@item -Wcomment
@findex Wcomment (cpp)
Warn whenever a comment-start sequence @samp{/*} appears in a comment.

@item -Wall
@findex Wall (cpp)
Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not
@samp{-Wtraditional}).

@item -Wtraditional
@findex Wtraditional (cpp)
Warn about certain constructs that behave differently in traditional and
ANSI C.
@end ifset

@item -I @var{directory}
@findex I (cpp)
Add the directory @var{directory} to the end of the list of
directories to be searched for header files.
@c (@xref{Include Syntax}).
This can be used to override a system header file, substituting your
own version, since these directories are searched before the system
header file directories.  If you use more than one @samp{-I} option,
the directories are scanned in left-to-right order; the standard
system directories come after.@refill

@item -I-
Any directories specified with @samp{-I} options before the @samp{-I-}
option are searched only for the case of @samp{#include "@var{file}"};
they are not searched for @samp{#include <@var{file}>}.

If additional directories are specified with @samp{-I} options after
the @samp{-I-}, these directories are searched for all @samp{#include}
directives.

In addition, the @samp{-I-} option inhibits the use of the current
directory as the first search directory for @samp{#include "@var{file}"}.
Therefore, the current directory is searched only if it is requested
explicitly with @samp{-I.}.  Specifying both @samp{-I-} and @samp{-I.}
allows you to control precisely which directories are searched before
the current one and which are searched after.

@item -nostdinc
Do not search the standard system directories for header files.
Only the directories you have specified with @samp{-I} options
(and the current directory, if appropriate) are searched.

@ifset gcc2
@item -nostdinc++
Do not search for header files in the C++-specific standard directories,
but do still search the other standard directories.
(This option is used when building @samp{libg++}.)
@end ifset

@item -D @var{name}
@findex D (cpp)
Predefine @var{name} as a macro, with definition @samp{1}.

@item -D @var{name}=@var{definition}
Predefine @var{name} as a macro, with definition @var{definition}.
There are no restrictions on the contents of @var{definition}, but if
you are invoking the preprocessor from a shell or shell-like program
you may need to use the shell's quoting syntax to protect characters
such as spaces that have a meaning in the shell syntax.

@item -U @var{name}
@findex U (cpp)
Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are
specified for one name, the @samp{-U} beats the @samp{-D} and the name
is not predefined.

@item -undef
@findex undef (cpp)
Do not predefine any nonstandard macros.

@ifset gcc1
@item -d
@findex d (cpp)
Instead of outputting the result of preprocessing, output a list of
@samp{#define} commands for all the macros defined during the
execution of the preprocessor.
@end ifset

@ifset gcc2
@item -dM
@findex dM (cpp)
Instead of outputting the result of preprocessing, output a list of
@samp{#define} commands for all the macros defined during the
execution of the preprocessor, including predefined macros.  This gives
you a way of finding out what is predefined in your version of the
preprocessor; assuming you have no file @samp{foo.h}, the command

@example
touch foo.h; cpp -dM foo.h
@end example

@noindent
will show the values of any predefined macros.

@item -dD
@findex dD (cpp)
Like @samp{-dM} except in two respects: it does @emph{not} include the
predefined macros, and it outputs @emph{both} the @samp{#define}
commands and the result of preprocessing.  Both kinds of output go to
the standard output file.
@end ifset

@item -M
@findex M (cpp)
Instead of outputting the result of preprocessing, output a rule
suitable for @code{make} describing the dependencies of the main
source file.  The preprocessor outputs one @code{make} rule containing
the object file name for that source file, a colon, and the names of
all the included files.  If there are many included files then the
rule is split into several lines using @samp{\}-newline.

This feature is used in automatic updating of makefiles.

@item -MM
@findex MM (cpp)
Like @samp{-M} but mention only the files included with @samp{#include
"@var{file}"}.  System header files included with @samp{#include
<@var{file}>} are omitted.

@ifset gcc1
@item -i @var{file}
@findex i (cpp)
Process @var{file} as input, discarding the resulting output, before
processing the regular input file.  Because the output generated from
@var{file} is discarded, the only effect of @samp{-i @var{file}} is to
make the macros defined in @var{file} available for use in the main
input.
@end ifset

@ifset gcc2
@item -MD
@findex MD (cpp)
Like @samp{-M} but the dependency information is written to files with
names made by replacing @samp{.c} with @samp{.d} at the end of the
input file names.  This is in addition to compiling the file as
specified---@samp{-MD} does not inhibit ordinary compilation the way
@samp{-M} does.

In Mach, you can use the utility @code{md} to merge the @samp{.d} files
into a single dependency file suitable for using with the @samp{make}
command.

@item -MMD
@findex MMD (cpp)
Like @samp{-MD} except mention only user header files, not system
header files.

@item -H
@findex H (cpp)
Print the name of each header file used, in addition to other normal
activities.

@item -imacros @var{file}
@findex imacros (cpp)
Process @var{file} as input, discarding the resulting output, before
processing the regular input file.  Because the output generated from
@var{file} is discarded, the only effect of @samp{-imacros @var{file}}
is to make the macros defined in @var{file} available for use in the
main input.

@item -include @var{file}
@findex include (cpp)
Process @var{file} as input, and include all the resulting output,
before processing the regular input file.

@item -lang-c
@itemx -lang-c++
@itemx -lang-objc
@itemx -lang-objc++
@findex lang-c (cpp)
@findex lang-c++ (cpp)
@findex lang-objc (cpp)
@findex lang-objc++ (cpp)
Specify the source language.  @samp{-lang-c++} makes the preprocessor
handle C++ comment syntax, and includes extra default include
directories for C++, and @samp{-lang-objc} enables the Objective C
@samp{#import} directive.  @samp{-lang-c} explicitly turns off both of
these extensions, and @samp{-lang-objc++} enables both.

These options are generated by the compiler driver @code{gcc}, but not
passed from the @samp{gcc} command line.

@item -lint
@findex lint (cpp)
Look for commands to the program checker @code{lint} embedded in
comments, and emit them preceded by @samp{#pragma lint}.  For example,
the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint
NOTREACHED}.

This option is available only when you call @code{cpp} directly;
@code{gcc} will not pass it from its command line.

@item -$
Forbid the use of @samp{$} in identifiers.  This is required for ANSI
conformance.  @code{gcc} automatically supplies this option to the
preprocessor if you specify @samp{-ansi}, but @code{gcc} doesn't
recognize the @samp{-$} option itself---to use it without the other
effects of @samp{-ansi}, you must call the preprocessor directly.
@end ifset
@end table

@node     Predefined Macros, , Invoking CPP, The Preprocessor
@comment  node-name, next,     previous,    up
@section Predefined Macros
@cindex Predefined Macros
@cindex Macros, Predefined

The standard predefined macros are available with the same meanings
regardless of the machine or operating system on which you are using GNU C.
Their names all start and end with double underscores. Those preceding
@code{__GNUC__} in this table are standardized by ANSI C; the
rest are GNU C extensions.

@table @code
@item __FILE__
@cindex __FILE__ (cpp macro)
This macro expands to the name of the current input file, in the form of
a C string constant.  The precise name returned is the one that was
specified in @samp{#include} or as the input file name argument.

@item __LINE__
@cindex __LINE__ (cpp macro)
This macro expands to the current input line number, in the form of a
decimal integer constant.  While we call it a predefined macro, it's
a pretty strange macro, since its ``definition'' changes with each
new line of source code.

This and @samp{__FILE__} are useful in generating an error message to
report an inconsistency detected by the program; the message can state
the source line at which the inconsistency was detected. For example,

@example
fprintf (stderr,
	 "Internal error: negative string length "
         "%d at %s, line %d.",
         length, __FILE__, __LINE__);
@end example

A @samp{#include} command changes the expansions of @samp{__FILE__}
and @samp{__LINE__} to correspond to the included file.  At the end of
that file, when processing resumes on the input file that contained
the @samp{#include} command, the expansions of @samp{__FILE__} and
@samp{__LINE__} revert to the values they had before the
@samp{#include} (but @samp{__LINE__} is then incremented by one as
processing moves to the line after the @samp{#include}).

The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered
if a @samp{#line} command is used.
@c @xref{Combining Sources}.

@ifset gcc2
@item __INCLUDE_LEVEL__
@cindex __INCLUDE_LEVEL_ (cpp macros)
This macro expands to a decimal integer constant that represents the
depth of nesting in include files.  The value of this macro is
incremented on every @samp{#include} command and decremented at every
end of file.
@end ifset

@item __DATE__
@cindex __DATE__ (cpp macro)
This macro expands to a string constant that describes the date on
which the preprocessor is being run.  The string constant contains
eleven characters and looks like @samp{"Jan 29 1987"} or
@w{@samp{"Apr 1 1905"}}.

@item __TIME__
@cindex __TIME__ (cpp macro)
This macro expands to a string constant that describes the time at
which the preprocessor is being run.  The string constant contains
eight characters and looks like @samp{"23:59:01"}.

@item __STDC__
@cindex __STDC__ (cpp macro)
This macro expands to the constant 1, to signify that this is ANSI
Standard C. (Whether that is actually true depends on what C compiler
will operate on the output from the preprocessor.)

@item __GNUC__
@cindex __GNUC__ (cpp macro)
This macro is defined if and only if this is GNU C.  This macro is
defined only when the entire GNU C compiler is in use; if you invoke
the preprocessor directly, @samp{__GNUC__} is undefined.

@item __STRICT_ANSI__
@cindex __STRICT_ANSI__ (cpp macro)
This macro is defined if and only if the @samp{-ansi} switch was
specified when GNU C was invoked.  Its definition is the null string.
This macro exists primarily to direct certain GNU header files not to
define certain traditional U**x constructs which are incompatible with
ANSI C.

@ifset gcc2
@item __BASE_FILE__
@cindex __BASE_FILE__ (cpp macro)
This macro expands to the name of the main input file, in the form
of a C string constant.  This is the source file that was specified
as an argument when the C compiler was invoked.
@end ifset

@item __VERSION__
@cindex __VERSION__ (cpp macro)
This macro expands to a string which describes the version number of
GNU C.  The string is normally a sequence of decimal numbers separated
by periods, such as @samp{"1.18"}.  The only reasonable use of this
macro is to incorporate it into a string constant.

@item __OPTIMIZE__
@cindex __OPTIMIZE__ (cpp macro)
This macro is defined in optimizing compilations.  It causes certain
GNU header files to define alternative macro definitions for some
system library functions.  It is unwise to refer to or test the
definition of this macro unless you make very sure that programs will
execute with the same effect regardless.

@item __CHAR_UNSIGNED__
@cindex __CHAR_UNSIGNED__ (cpp macro)
This macro is defined if and only if the data type @code{char} is
unsigned on the target machine. It exists to cause the standard
header file @file{limit.h} to work correctly.  It is bad practice
to refer to this macro yourself; instead, refer to the standard
macros defined in @file{limit.h}.

@item __MSHORT__
@cindex __MSHORT__ (cpp macro)
This macro is defined, if @file{gcc.ttp} is invoked with the
@samp{-mshort} option, which causes integers to be 16 bit. Please
carefully examine the prototypes in the @samp{#include <>} headers
for types before using @samp{-mshort}.@refill

@item __MINT__
@cindex __MINT__ (cpp macro)
This macros is defined, if @file{gcc.ttp} is invoked with the
@samp{-mint} option. This macros activates some portions of the header
files, which are MiNT specific. Up to version 8 of the MiNT libraries and
headers the header files of J.R.Bammi's libraries are compatible with
the ones from Eric Smith's library. Therefore if you were writing
programs for MiNT you could stick to Bammi's headers and use the
@samp{-mint} option. I don't know, if header files are still compatible
with version 10 of the MiNT libraries.

@ifset gcc2
@item __MBASE__
@itemx __MBASESTR__
@cindex __MBASE__ (cpp macro)
@cindex __MBASESTR__ (cpp macro)
hudli wirz
@end ifset

@end table

Apart from the above listed macros, there are usually some more to
to indicate what type of system and machine is in use. For example
@samp{unix} is normally defined on all U**x systems. Other macros
describe more or less the type of CPU the system runs on. GNU CC for
the Atari ST has the following macros predefined.

@itemize @bullet
@item
@samp{atarist}

@item
@samp{gem}

@item
@samp{m68k}
@end itemize

Please keep in mind, that these macros are only defined, if the
preprocessor is invoked from the compiler driver @file{gcc.ttp}.

These predefined symbols are not only nonstandard, they are contrary to the
ANSI standard because their names do not start with underscores.  However,
the GNU C preprocessor would be useless if it did not predefine the same
names that are normally predefined on the system and machine you are using.
Even system header files check the predefined names and will generate
incorrect declarations if they do not find the names that are expected.

The @samp{-ansi} option which requests complete support for ANSI C
inhibits the definition of these predefined symbols.
@page

@node     The Assembler, The Utilities, The Preprocessor, Top
@comment  node-name,     next,          previous,         up
@chapter The GNU Assembler (GAS)
@cindex Assembler
@cindex gcc-as.ttp (executable)

  Most of the time you will be programming in C. But there may certain
situations, where it is feasible to write in assembler. Time is usually
a main reason to dive into assembler programming, when you have to
squeeze the last redundant machine cycle out of your routine, to meet
certain time limits. Another reason might be, that you have to do very
low level stuff like fiddling with bits in the registers of a peripheral
chip. An example for low level stuff is the startup module
@file{crt0.o}, which is written in assembler.

  If you already have some experience in assembler programming, you
might miss the feature of creating macros. This is not really a lack
given the fact, that the assembler originated from an U**x environment.
Under this operating system there is a tools for nearly every purpose.
If you were in the need of an extensive macros facility, you would use
the M4 macro processor. A GNU version of the M4 macro processor exists.
It should be no problem to port it to the Atari with GCC. For some macro
processing tasks you just as well use the C preprocessor. What I
personally miss is the ability to produce a listing, but this will be
fixed with GAS 1.92.

  One command line option was introduced only very lately. The changes
for the option @samp{-m68040} were part of update 20, which Bammi
released around end of April 1992. The assembler identifies itself, when
invoked with the @samp{-v} option with the string @samp{GNU assembler
version 1.38 atariST PatchLevel 2}.

@menu
* Invoking AS::         Command line options supported by @samp{gcc-as.ttp}.
* Syntax::              Description of the assembler syntax.
* Pseudo Opcodes::      Pseudo Opcodes supported by @samp{gcc-as.ttp}.
* Asmtrans::            Converting Motorola Assembler Syntax
@end menu

@node     Invoking AS, Syntax, The Assembler, The Assembler
@comment  node-name,   next,   previous, up
@section Invoking the Assembler
@cindex Invoking the Assembler

@file{gcc-as.ttp} supports the following command line options. The output
is written to @samp{a.out} by default.

@table @samp
@cindex Options (as)
@item -G
@findex G (as)
assembles the debugging information the C compiler included into the
output. Without this flag the debugging information is otherwise
discarded.

@item -L
@findex L (as)
Normally all labels, that start with a @samp{L} are discarded and don't
show up as symbols in the object code module. They are local to that
assembler module. If the @samp{-L} option is given, all local labels
will be included in the object code module.

@c @item -l
@c @findex l (as)
@c keep externals to 2 bit offset.
@item -m68000
@itemx -m68010
@itemx -m68020
@itemx -m68040
@findex m68000 (as)
@findex m68010 (as)
@findex m68020 (as)
@findex m68040 (as)
These options modify the behavior of assembler in respect of the used
CPU. The M68020, for example, allows relative branches with 32-bit
offset.

@item -o@var{filename}
@findex o (as)
writes the output to @var{filename} instead of @samp{a.out}.

@item -R
@findex R (as)
The information, which normally would be assembled into the data section
of the program, is moved into the text section.

@item -v
@findex v (as)
displays the version of the assembler.

@item -W
@findex W (as)
suppresses all warning messages.
@end table

@node     Syntax,     Pseudo Opcodes, Invoking AS, The Assembler
@comment  node-name,  next,           previous,    up
@section Syntax
@cindex Syntax (as)

The assembler uses a slightly modified syntax from the one you might
know from other 68000 assemblers, which use the original Motorola
syntax. The next sections trys to describe the syntax, GAS uses.

The most obvious differences are the missing @samp{.} and the usage of
the at sign (@samp{@@}). The original Motorola syntax uses the @samp{.}
to separate the size modifier (@code{b}, @code{w}, @code{l}) from the
main instruction. In Motorola syntax one would write @samp{move.l #1,d0}
to move a long word with value 1 into register @code{d0}. With GAS you
simple write @samp{movel #1,d0}. The @samp{@@} is used to mark an
indirection equivalent to the Motorola parentheses. To move a long word
of value 1 to the location addressed by @code{a0}, you have to write
@samp{movel #1,a0@@}. The equivalent instruction expressed in Motorola
syntax is @samp{move.l #1,(a0)}. The @samp{#} indicates immediate data
in both cases.@refill

@menu
* Registers::		This section describes the register names and
			 addressing modes.
* Labels::		This section explains the rules for labels and
			 identifier.
* Comments::		The rules for inserting comments.
* Constants::		Numerical and string constants.
* Assignments::		How to do assignments and the available operators.
* Segments::		About segments, location counters and labels.
* Types::		About what type a label or a symbol can be.
@end menu

@node     Registers, Labels, Syntax, Syntax
@comment  node-name,  next,  previous,  up
@subsection Register Names and Addressing Modes

The register mnemonics are @code{d0}@dots{}@code{d7} for the data registers
and @code{a0}@dots{}@code{a7} or @code{sp} for address register and the stack
pointer. @code{pc} is the program counter, @code{sr} the status register,
@code{ccr} the condition code register and @code{usp} the user stack
pointer.@refill
@cindex Register Names

The following table shows the operands GAS can parse. (The first part
part describe the used abbreviations. The second part show the addressing
modes with a equivalent C expression.)

@table @code
@item numb:
a 8 bit number

@item numw:
a 16 bit number

@item numl:
a 32 bit number

@item dreg:
data register 0@dots{}7

@item reg:
address or data register

@item areg:
address register 0@dots{}7

@item apc:
address register or PC

@item num:
a 16 or 32 bit number

@item num2:
a 16 or 32 bit number

@item sz:
@code{w} or @code{l}; if omitted, @code{l} is  assumed.

@item scale:
1 2 4 or 8. If omitted, 1 is assumed.
@end table

@noindent
@strong{Addressing Modes}:
@cindex Addressing Modes

@table @code
@item Immediate Data
@example
#num                          --> NUM
@end example

@item Data- or Address Register Direct
@example
dreg                          --> dreg
areg                          --> areg
@end example

@item Address Register Indirect
@example
areg@@                         --> *(areg)
@end example

@item Address Register Indirect with Postincrement or Predecrement
@example
areg@@+                        --> *(areg++)
areg@@-                        --> *(--areg)
@end example

@item Address Register (or PC) Indirect with Displacement
@example
apc@@(numw)                    --> *(apc+numw)
@end example

@item Address Register (or PC) Indirect with Index (8-Bit Displacement)
@itemx (M68020 only)
@example
apc@@(num,reg:sz:scale)        --> *(apc+num+reg*scale)
apc@@(reg:sz:scale)            --> same, with num=0
@end example

@item Memory Indirect Postindexed
@itemx (M68020 only)
@example
apc@@(num)@@(num2,reg:sz:scale) --> *(*(apc+num)+num2+reg*scale)
apc@@(num)@@(reg:sz:scale)      --> same, with num2=0
apc@@(num)@@(num2)              --> *(*(apc+num)+num2)
                                 (previous mode without an index reg)
@end example

@item Memory Indirect Preindexed
@itemx (M68020 only)
@example
apc@@(num,reg:sz:scale)@@(num2) --> *(*(apc+num+reg*scale)+num2)
apc@@(reg:sz:scale)@@(num2)     --> same, with num=0
@end example

@item Absolute Address
@example
num:sz                        --> *(num)
num                           --> *(num) (sz L assumed)
@end example
@end table

@node     Labels, Comments, Registers, Syntax
@comment  node-name,  next,  previous,  up
@subsection Labels and Identifiers
@cindex Labels (as)
@cindex Identifier (as)

User defined identifiers are basically defined by the same rules as C
identifier. They may contain the digits 0@dots{}9, the letters A@dots{}z
and the underscore and must not start with a digit. Identifier, which
end with a @samp{:} are labels. A special form of labels starts with a
@samp{L} or consists of only a digit. Both types are local labels, which
disappear, when the assembly is complete (unless the @samp{-L} option
was specified). They can't be used to resolve external references.  The
@samp{L} type label are referenced by their name, just as any other
label. The digit type labels form a special kind of local labels. You
might also call them temporary labels. They are especially useful when
you have to create small loops, which poll a peripheral or fill a memory
area. They are referenced by appending either a @samp{f}, for a forward
reference, or a @samp{b}, for a backward reference, to the digit. Lets
look at the following example, which is used to split a memory area
starting at @code{0x80000}. All data on an even addresses is copied to
the area starting at @code{0x70000}; all data from odd addresses goes to
the area starting at @code{0x78000}.@refill

@example
start:
        lea     0x80000,a0
        lea     0x70000,a1
        lea     0x78000,a2
        movel   #0x7fff,d5
0:                              | label @samp{0} is defined
        moveb   a0@@+,a1@@+
        moveb   a0@@+,a2@@+
        dbra    d5,0b           | reference of label @samp{0}
        @dots{}
@end example

The label @samp{0} is referenced 3 lines later by @samp{0b}, since the
reference is backward. You can use the label @samp{0} again at a later
time to construct more such loops. Since this temporary labels are
restricted to one digit in length, you can only build constructs, which
use 10 temporary labels at the same time.

@node     Comments, Constants, Labels, Syntax
@comment  node-name,  next,  previous,  up
@subsection Comments
@cindex Comments (as)

The above example also shows, that comments start with a @samp{|}.
@samp{#} is also used to mark a comments. The C compiler and the
preprocessor generate lines, that start with a @samp{#}.

@node  Constants, Assignments, Comments, Syntax
@comment  node-name,  next,  previous,  up
@subsection Numerical and String Constants
@cindex Constants, Numerical (as)
@cindex Constants, String (as)

Numerical values are given the same way as in a C programs. By default
number are taken to be decimal. A leading @samp{0} denotes an octal and
a @samp{0x} a hexadecimal value. Floating point numbers start with a
@samp{0f}. The optional exponent starts with a @samp{e} or @samp{E}.

String constants are equivalent to C defined. They are enclosed
in @samp{"}. Some special character constants are defined by @samp{\}
and a following letter. These characters are possible:

@table @code
@item \b
Backspace, Code 0x08
@item \t
Tab, Code 0x09
@item \n
Line Feed, Code 0x0a
@item \f
Form Feed, Code 0x0c
@item \r
Carriage Return, Code 0x0d
@item \\
Backslash itself
@item \"
Double Quote itself
@item \@var{number}
were @var{number} is a octal number with up to 3 digits specifying the
character code.
@end table

@node     Assignments, Segments, Constants, Syntax
@comment  node-name,  next,  previous,  up
@subsection Assignments and Operators
@cindex Assignments (as)
@cindex Operators (as)

A @samp{=} is used to assign a value to a Symbol.

@example
Lexp_frame = 8
@end example

@noindent
This is equivalent to the @samp{equ} directive other assemblers use.

GAS supports addition (+), subtraction (-), multiplication(*), division
(/), right shift (>), left shift (<), and (&), or (|), not (!), xor (^)
and modulo (%) in expressions. The order of precedence is

@example
        Rank    Examples
lowest   0       operand, (expression)
         1       + -
         2       & ^ ! |
         3       * / % < >
@end example

Parentheses are used to coerce the order of evaluation.

@node     Segments, Types, Assignments, Syntax
@comment  node-name,  next,  previous,  up
@subsection Segments, Location Counters and Labels
@cindex Segments (as)
@cindex Labels (as)
@cindex Location Counter (as)

A program written in assembler language may be broken into three
different segments; the TEXT, DATA and BSS sections. Pseudo opcodes are
used to switch between the sections. The assembler maintains a location
counter for each segment. When a label is used in the assembler input,
it is assigned the current value of the active location counter. The
location counter is incremented with every byte, that the assembler
outputs. GAS actually allows you to have more than one TEXT or DATA
segment. This is so to ease code generation by high level compilers.
The assembler concatenates the different sections in the end to form
continuous regions of TEXT and/or DATA. When you do assembly programming
by hand you would stick to the pseudo opcodes @samp{.text} or
@samp{.data}, which use text or data segment with number 0 by default.

@node     Types,  , Segments, Syntax
@comment  node-name,  next,  previous,  up
@subsection Types
@cindex Types (as)

Symbol and Labels can be of one of three type. A Symbol is @emph{absolute};
when it's values is known at assembly time. A assignment like
@samp{Lexp_frame = 8} gives the symbol @samp{Lexp_frame} the absolute
value 8. A symbol or label, which contains an offset from the beginning
of a section, is called @emph{relocatable}. The actual value of this symbol
can only be determined after the linking process or when the program is
running in memory. The third type of symbols are @emph{undefined externals}.
The actual value of this symbol is defined in an other program.

When different types of symbols are combined to form expressions the
following rules apply: (@code{abs} = absolute, @code{rel} = relocatable,
@code{ext} = undefined external)

@example
abs + abs => abs
abs + rel = rel + abs => rel
abs + ext = ext + abs => ext

abs - abs => abs
rel - abs => rel
ext - abs => ext
rel - rel => abs
(makes only sense, when both relocatable expression are relative to
same segment)
@end example

All other possible operators are only useful to form expressions with
@emph{absolute} values or symbols.

@node     Pseudo Opcodes, Asmtrans, Syntax, The Assembler
@comment  node-name, next,  previous, up
@section Supported Pseudo Opcodes (Directives)
@cindex Pseudo Opcodes (as)
@cindex Directives (as)

All pseudo opcodes start with a @samp{.}. They are followed by 0, 1 or
more expressions separated by commas (depending on the directive). The
following table omits the pseudo opcodes, which include special
information for debugging purposes (for GDB).

@table @code
@item .abort
@cindex .abort (as pseudo opcode)
aborts the assembly on the point.

@item .align @var{integer}
@cindex .align (as pseudo opcode)
aligns the current segment in size to @var{integer} power of 2. The
maximum value of @var{integer} is 15. The lines

@example
.text
some code @dots{}
.align 10               | 2^10 = 1024
.data
some more code @dots{}
.align 10               | 2^10 = 1024
@end example

will create text and data sections, which both have the size 1024,
although the actual code, that goes into the sections may be smaller.

@item .ascii @var{string}[,@var{string},@dots{}]
@cindex .ascii (as pseudo opcode)
includes the @var{string}('s) in the assembly output.

@item .asciz @var{string}[,@var{string},@dots{}]
@cindex .asciz (as pseudo opcode)
This directive is the same as above, but additionally appends a
@samp{\0} character to the string.

@item .byte @var{expr}[,@var{expr},@dots{}]
@cindex .byte (as pseudo opcode)
puts consecutive bytes with value @var{expr} into the output.

@item .comm @var{identifier},@var{integer}
@cindex .comm (as pseudo opcode)
creates a common area of @var{integer} bytes in the current segment,
which is referenced by @var{identifier}. The @var{identifier} is
visible from the outside of the module. It can therefore be used to
resolve external reference from other modules.

@item .data [@var{integer}]
@cindex .data (as pseudo opcode)
switches to DATA section @var{integer}. If @var{integer} is omitted,
data section 0 is selected.

@item .desc
@cindex .desc (as pseudo opcode)
Whatsit good for ???

@item .double @var{double}[,@var{double},@dots{}]
@cindex .double (as pseudo opcode)
puts consecutive doubles with value @var{double} into the output.

@item .even
@cindex .even (as pseudo opcode)
sets the location counter of the current segment to the next even
value.

@item .file
@itemx .line
@cindex .file (as pseudo opcode)
@cindex .line (as pseudo opcode)
If a file is assembled, which was generated by a compiler or preprocessed
by the C preprocessor, the input may contain lines like @samp{# 132 stdio.h}.
These lines are change by the assembler to the form

@example
.line 132
.file stdio.h
@end example

@item .fill @var{count},@var{size},@var{expr}
@cindex .fill (as pseudo opcode)
puts @var{count} areas with @var{size} into the output. Each area
contains the value @var{expr}. @var{size} may be an even number up to or
equal to 8. The line

@example
.fill 3, 4, 0xa5a
@end example

would put the following byte sequence in the output (@samp{|} is only
used to mark the size of the area.)

@example
00 00 0a 5a | 00 00 0a 5a | 00 00 0a 5a
@end example

@item .float @var{float}[,@var{float},@dots{}]
@cindex .float (as pseudo opcode)
puts consecutive floats with value @var{float} into the output.

@item .globl @var{identifier}[,@var{identifier},@dots{}]
@cindex .globl (as pseudo opcode)
When labels or identifiers are assigned, they are only locally defined.
The @code{.globl} directive gives @var{identifier} external scope. The
label can therefore be used to resolve external references from other
modules. @var{identifier} don't have to be assigned in the current
module, but can be defined in another module.

@item .int @var{expr}[,@var{expr},@dots{}]
@cindex .int (as pseudo opcode)
puts consecutive integers (32 bit) with value @var{expr} into the output.

@item .lcomm @var{identifier},@var{integer}
@cindex .lcomm (as pseudo opcode)
is basically the same as @code{.comm}, except that area is allocated in
the BSS segment. The scope of @var{identifier} is only local (only
visible in the module, where it is defined).

@item .long @var{expr}[,@var{expr},@dots{}]
@cindex .long (as pseudo opcode)
same as @code{int}.

@item .lsym @var{identifier},@var{expr}
@cindex .lsym (as pseudo opcode)
sets the local @var{identifier} to the value of @var{expr}. The
@var{identifier} is referenced by preceding it with a @samp{L}.
(@code{L@var{identifier}}) (When I tried this, the linker threw a
bomb. Trying again crashed the system.)

@item .octa
@cindex .octa (as pseudo opcode)
Whatsit good for ???

@item .org @var{expr}
@cindex .org (as pseudo opcode)
sets the location counter of the current segment to @var{expr}.

@item .quad
@cindex .quad (as pseudo opcode)
Whatsit good for ???

@item .set @var{identifier},@var{expr}
@cindex .set  (as pseudo opcode)
sets @var{identifier} to the value of @var{expr}. If @var{identifier} is
not explicitly marked external by the @code{.globl} directive, is has only
local scope.

@item .short @var{expr}[,@var{expr},@dots{}]
@cindex .short (as pseudo opcode)
puts consecutive shorts (16 bit) with value @var{expr} into the output.

@item .space @var{count}, @var{expr}
@cindex .space (as pseudo opcode)
puts @var{count} consecutive number of bytes with value @var{expr} into
the output. The line

@example
.space 5,3
@end example

is equivalent to

@example
.byte 3, 3, 3, 3, 3
@end example

The @code{space} directive is a special form of the @code{fill} directive.

@item .text [@var{integer}]
@cindex .text (as pseudo opcode)
switches to TEXT section @var{integer}. If @var{integer} is omitted,
text section 0 is selected.

@item .word @var{expr}[,@var{expr},@dots{}]
@cindex .word (as pseudo opcode)
same as @code{.short}.
@end table

@node     Asmtrans,  , Pseudo Opcodes, The Assembler
@comment  node-name,  next,  previous,  up
@section Converting Motorola Assembler Syntax
@cindex Asmtrans
@cindex Converting Motorola Syntax
@cindex Motorola Syntax, Converting

  There is a utility, which is part of the MiNT source distribution
since around 0.96 pl14. It is called @file{asmtrans.ttp}. This utility
is used to convert some of MiNT's source files, which are written in
standard Motorola assembler syntax into GAS syntax. Eric R. Smith wrote
this little utility, so that he doesn't have to maintain the assembler
files in more than on syntax versions.

  The general syntax to invoke @file{asmtrans.ttp} is:

@example
asmtrans [@var{options}] @var{infile}
@end example

  The following options are possible:

@table @samp
@item -gas
@findex gas (asmtrans)
converts the input file into GAS syntax, also known as MIT syntax. Apart
from the modification of the standard assembler intructions the
following pseude opcodes or assembler directives are mapped:

@itemize @bullet
@c @item
@c @samp{mmusr} @result{} @samp{psr}
@c @item
@c @samp{fpiar} @result{} @samp{fpi}
@item
@samp{XREF} @result{} @samp{.globl}

@item
@samp{XDEF} @result{} @samp{.globl}

@item
@samp{TEXT} @result{} @samp{.text}

@item
@samp{DATA} @result{} @samp{.data}

@item
@samp{BSS} @result{} @samp{.data}

@item
@samp{END} @result{} @samp{| END}

@item
@samp{dc.l} @result{} @samp{.long}

@item
@samp{dc.w} @result{} @samp{.word}

@item
@samp{dc.b} @result{} @samp{.byte}
@end itemize

@item -asm
@findex asm (asmtrans)
converts the input file into ASM syntax (I think the assembler of the
Lattice compiler is meant). This option only causes some assembler
directives to be changed.

@itemize @bullet
@item
@samp{TEXT} @result{} @samp{SECTION TEXT}

@item
@samp{DATA} @result{} @samp{SECTION DATA}

@item
@samp{BSS} @result{} @samp{SECTION BSS}
@end itemize

@item -purec
@findex purec (asmtrans)
converts the input file into Pure C syntax for the assembler from the Pure
C compiler. As far as I can tell, the only effect, that this option has
is, that a leading underscore is removed from every label.

@item -o @var{outfile}
@findex o (asmtrans)
writes the output into the file @var{outfile}.
@end table

  @file{asmtrans.ttp} supports some simple directives to allow
conditional processing. The directives are very similar to the ones of
standard C preprocessor except that they don't start with @samp{#} but
with @samp{%}. The following directives are supported.

@table @code
@item %define @var{name}

@item %include @var{file}

@item %ifdef @var{name}

@item %ifndef @var{name}

@item %else

@item %endif

@end table

  The directives behave equivalent to their cpp counter parts. The
definition @var{name} may consist of the same characters as any C
symbol. It may begin with a @samp{_} or a letter and continue with
either @samp{_}, letter or digit.
@page

@node     The Utilities, Debugging, The Assembler, Top
@comment  node-name,     next,      previous,      up
@chapter The Utilities
@cindex Utilities

This chapter describes the programs, which don't actually convert
the source code into object code, but instead combine several object
code modules to a runnable program or an object code library. Other
programs can be used to print symbol information from either the
object code or the executable. The last group of utility programs
modify the executables in terms of memory usage and startup time.

@menu
* The Linker::          Command options supported by @samp{gcc-ld.ttp}
* The Archiver::        Command options supported by @samp{gcc-ar.ttp}
* Miscellaneous::       Commands to modify an existing executables or
                         obtain information from object or executable
                         files.
@end menu

@node     The Linker, The Archiver, The Utilities, The Utilities
@comment  node-name,  next,          previous,      up
@section The Linker @file{gcc-ld.ttp}
@cindex Linker
@cindex gcc-ld.ttp (executable)

A linker combines several object modules and extracts modules from a
library to produce a runnable program. During this process all undefined
symbol references are resolved. Additionally all sections from the object
modules, which belong to either the TEXT, DATA or BSS are moved to the
correct program segment. For example, all areas of all the object code
modules, which have the type TEXT, are moved to form one large TEXT
section. The same applies to the DATA and BSS sections.

For the most time you don't have invoke the linker explicitly. The
compiler driver does the job for you. But in case you have to, the
general syntax is:

@example
gcc-ld [@var{options}] $GNULIB\crt0.o @var{file}.o -l@var{library}
@end example

The above syntax assumes, that the executable is produced from C source
code, which normally makes is necessary to link a startup module and a
library. If an executable from a self contained assembler text is to be
created, the startup module @file{crt0.o} and the library might be
missing. @file{gcc-ld.ttp} creates a file @file{a.out} by default. The
linker can also append a DRI compatible or an extended symbol table to
the executable.

@file{gcc-ld.ttp} supports the following command line options. The
options @samp{-f} and @samp{-h} were introduced with update 29, which
brought the utilites to patchlevel 34 (March 1993).

@table @samp
@cindex Options (ld)
@c item -A
@c findex A (ld)
@c item -D@var{datasize}
@c findex D (ld) specified_data_size
@c item -d
@c findex d (ld) force_common_definition
@c item -e@var{entry_symbol}
@c findex e (ld) entry_symbol
@item -f@var{load flags}
@findex f (ld)
Set the program load flags to @var{load flags}. The default program load
flags is 7 (run and malloc in/from TT ram, fastload).
(@xref{toglclr.ttp} for additional info)

@item -h@var{altheap size}
@findex h (ld)
Set the minalt size in the executable header to @var{altheap size}.
The default value is zero. Remember that value is specified in
128k units. What this means is (quoting mintsrc/mem.c): If
(flags & F_ALTLOAD == 1), then we might decide to load in alternate
RAM if enough is available. "enough" is: if more alt ram than ST ram,
load there; otherwise, if more than (minalt+1)*128K alt ram available
for heap space, load in alt ram ("minalt" is the high byte of flags).

@item -l@var{library}
@findex l (ld)
Search @var{library} to satisfy unresolved references. The environment
variable @code{GNULIB} is used to locate the library. @code{GNULIB}
contains a @samp{,} or @samp{;} separated list of paths, each path
without a trailing slash or backslash.
@item -L@var{directory}
@findex L (ld)
Includes @var{directory} in the search path to locate a library.

@item -M
@findex M (ld)
During the linking process extensive information about the encountered
symbols is displayed.

@item -n
@findex n (ld)

@item -G
@findex G (ld)
Instead of the standard DRI compatible symbol table, an extended symbol
table is written, which allows symbol names to be up to 22 characters
long. Most of the other utility programs have been updated to work with
this format. The most benefit you get with @file{gprof.ttp} and
@file{szadb} (the adb-like debugger, originally written for the Sozobon
C compiler by Johann Rueg and Don Dugger and later significantly
improved by Michal Jaegermann).

@item -o@var{filename}
@findex o (ld)
The resulting output of the linking process is written to
@var{filename} instead to @file{a.out}.

@c item -r
@c findex -r (ld) relocatable_output
@c item -S
@c findex S (ld) strip_symbols = STRIP_DEBUGGER
@item -s
@findex s (ld)
prevents the linker from attaching a symbol table to the executable.

@c item -T@var{text_start}
@c findex T (ld) text_start, T_flag_specified
@item -t
@findex t (ld)
During the linking process the files loaded and the modules extracted
from a library are displayed.

@c item -u@var{symbol}
@c findex u (ld) sp->referenced = 1
@c item -X
@c findex X (ld) discard_locals = DISCARD_L
@item -x
@findex x (ld)
This option discards all local symbols from the DRI symbol table. All
global symbols are left in place.
@end table

@unnumberedsubsec @file{sym-ld.ttp}
@cindex sym-ld.ttp (executable)

@file{sym-ld.ttp} is a special version of the linker. His sole purpose
is to create a special symbol file used by the GNU debugger. The
following example show the usage. (@samp{$} is the prompt of a CLI,
@samp{*} is the GDB prompt, @samp{#} marks a comment)@refill

@example
$ gcc -c -g foo.c      # compile @samp{foo.c}
$ gcc -o foo.prg foo.o -lgnu # link with normal @file{gcc-ld.ttp}
$ sym-ld -o foo.sym $(GNULIB)\crt0.o foo.o -lgnu
                       # (or -lgnu16 if you use -mshort)
                       # link with @file{sym-ld.ttp} to get symbol file
$ gdb
* exec-file foo.prg    # executable (@file{gcc-ld.ttp} linked Atari
                         executable)
* symbol-file foo.sym  # symbols file (@file{sym-ld.ttp} @samp{-o} linked)
* run
* <start doing gdb commands here>
 @dots{}
* q
$                      # back
@end example

  Note the line in the example, where @file{sym-ld.ttp} is invoked. A
library @file{gnugdb.olb} is used to create the symbol file. This is
just like the normal library @file{gnu.olb} except, that is was compiled
with the @samp{-g} option. If you don't have this library, use the
normal library (@samp{-lgnu}). In this case you can't single step
through library functions at the source level. Also note, that
@file{sym-ld.ttp} is invoked without the @samp{-r} option. This option
was only necessary for some very early versions of @file{gdb}.

  For a bit more detailed info about debugging with @file{gdb} turn to
chapter @xref{Debugging}.

@node     The Archiver, Miscellaneous, The Linker, The Utilities
@comment  node-name,    next,          previous,   up
@section The Archiver @file{gcc-ar.ttp}
@cindex Archiver
@cindex gcc-ar.ttp (executable)

The archivers main purpose is to make things in programming life
easier. The archiver combines several object modules into one large
library. At a later time the linker will then retrieve the modules
needed to resolve all references. Without the library you would have to
supply all modules by hand on the command line or the linker would have
to search through all the files to resolve the references (The library
@file{gnu.olb} contains around 150 modules).

The general syntax for invoking @file{gcc-ar.ttp} is:

@example
gcc-ar @var{option} [@var{position}] @var{library} [@var{module}]
@end example

The @var{option} specifies the action to be taken on the @var{library}
or a @var{module} of that @var{library}. @var{option} also includes
modifiers for the action. The optional @var{position} argument is a
member of the @var{library}. It is used, to mark a specific position in
the @var{library}; an @samp{add} operation would than place a new module
before or after that @var{position}. The next argument specifies the
library. The recommended naming convention for the creation of a new
libraries is @file{@var{library}.olb}. If you don't use this convention,
the compiler driver @file{gcc.ttp} will have trouble to find them.
@var{module} is usually an object code file generated by the compiler.

@file{gcc-ar.ttp} supports the following command line options. If you
don't use a @var{position} the named module is appended or moved to the
end of the library

@table @samp
@cindex Options (ar)
@item a
@findex a (ar)
The @samp{add}, @samp{replace} or @samp{move} operation should place the
@var{module} @strong{after} @var{position}.

@item b
@findex b (ar)
The @samp{add}, @samp{replace} or @samp{move} operation should place the
@var{module} @strong{before} @var{position}.

@item c
@findex c (ar)
If the specified @var{library} does not exist, it is silently created.
Without this option @file{gcc-ar.ttp} would give you a notice, that it
created a new library.

@item d
@findex d (ar)
deletes @var{module} from the @var{library}.

@item i
@findex i (ar)
This is the same as option @samp{b}.

@item l
@findex l (ar)
This option is ignored. (Why is there in the first place ??)

@item m
@findex m (ar)
Move a member around inside the library.

@item o
@findex o (ar)
preserves the modification time of a module, that is extracted from the
library.

@item p
@findex p (ar)
This option pipes the specified @var{module} directly to
@samp{<stdout>}.

@item q
@findex q (ar)
A quick append is performed.

@item r
@findex r (ar)
causes @var{module} to be replaced. If the named module is not already
present, it is appended. This is also the default action, when no
@var{option} is given.

@item s
@findex s (ar)
creates special member in the library called @samp{__.SYMDEF}, which
contains a directory of the external names defined by all the other
members.

@item t
@findex t (ar)
lists the members, that are currently in the @var{library}. If the
option @samp{v} is also given, additional information about file
permissions, user- and group-id's and last modification date of
the members are displayed. Of course, file permissions and user-
and group-id's don't make much sense on the Atari ST.

@item u
@findex u (ar)
If this option is given, an existing module in the library is only
replaced, if the modification time of the new module is newer than the
modification time of the one already in the library.

@item v
@findex v (ar)
gives you some additional information depending on the operation, that
currently performed.
@item x
@findex x (ar)
Extract @var{module} from the @var{library}.
@end table

@node     Miscellaneous, , The Archiver, The Utilities
@comment  node-name, next, previous,     up
@section Miscellaneous Utilities
@cindex Miscellaneous Utilities
@cindex Getting Information
@cindex Modifying Executablex

  There are some additional utility programs, which are used to either
modify an executable, or which give you some info about either object
files, object libraries or executables.

  Some programs, which are described in the following sections can only
work correctly, if the symbol table is still attached to the executable.
So, if you want to modify the memory usage of a program (with
@file{fixstk.ttp}) at a later time, you should keep the unstripped
executables around or use the command @file{xstrip.ttp} and keep only
the @code{_stksize} symbol.@refill

@menu
* gcc-nm.ttp::          List symbols from an object file or library.
* cnm.ttp::             List symbols attached to an executable.
* gcc-size.ttp::        List sizes of segments in object files.
* printstk.ttp::        Print the current value @code{_stksize}.
* fixstk.ttp::          Set the value of @code{_stksize}.
* toglclr.ttp::         Modify some program header bits.
* xstrip.ttp::          Strip an executable from symbol table.
* size68.ttp::          List sizes of segments and status of program
                         header bits of an executbale.
@end menu

@node     gcc-nm.ttp, cnm.ttp,  , Miscellaneous
@comment  node-name,  next,  previous,  up
@subsection @file{gcc-nm.ttp}
@cindex gcc-nm.ttp (executable)

  @file{gcc-nm.ttp} generates a listing about the symbols found in a GNU
object file or library. To list the symbols, which are attached to a TOS
executable use @file{cnm.ttp}.

  The output of @file{gcc-nm.ttp} looks like the following sample:

@example
00000870 b _Lbss
         U _alloca
000003b4 t _glob_dir_to_array
00000532 T _glob_filename
00000248 T _glob_vector
         U _malloc
0000086c D _noglob_dot_filenames
         U _opendir
         U _readdir
00000000 t gcc_compiled.
@end example

The first column displays the relative address of that symbol in
the object file. If the symbol has the type @code{U} (undefined
external) the space in left blank. The next column shows the type
of the symbol. In general, symbols, which have an external scope
(visible for other object module) are marked with an uppercase
letter. Symbols, which are local to the object file are marked
with lowercase letters. The following letters are possible:

@table @samp
@cindex Options (nm)
@item C
marks variables, which are defined in that source module, but not
initialized. A declaration like

@example
int variable;
@end example

would create a line marked with a @samp{C}. The first column would
show the size of that variable in bytes instead of the relative
address in the object module.

@item b
Variables, which are declared with

@example
static int variable;
@end example

are displayed with a @samp{b}.

@item D
marks variables, which are initialized at declaration time. A
declaration like

@example
int variable = 1;
@end example

would show as a line with a @samp{D} in it.

@item d
Variables, which are initialized at declaration time declared are
displayed with a @samp{d}. A declaration like

@example
static int variable = 1;
@end example

would create a line marked with a @samp{d}.

@item t,T
mark text (in other words: actual program code). Functions in your C
source, which have the storage class @code{static}, would be displayed
with a @samp{t}. All other functions in that source module, which are
visible to other modules, would show up with a @samp{T}.

@item U
All functions, which are defined in other modules and referenced in
this module, are displayed with a @samp{U}.
@end table

@noindent
The last column shows the symbol name.

@file{gcc-nm.ttp} supports the following command line options.

@table @samp
@item -a
@findex a (nm)
In case a file is compiled with the @samp{-g} or @samp{-gg} option,
special information for debugging purposes is included in the object
code. This information is listed by supplying the @samp{-a} option.

@item -g
@findex g (nm)
This option restricts the output to include only symbols, which have an
external scope.

@item -n
@findex n (nm)
Without any options the output is sorted in ascii order. By supplying
the @samp{-n}, the listing is sorted in numerical order by the addresses
in first column.

@item -o
@findex o (nm)
If this option is given, every output line is preceded by a filename in
the form @samp{@var{file}:}, naming the file in which the symbol
appears. If the file to be listed, is an archive, the line begins in the
form @samp{@var{library}(@var{member}):}.

@item -p
@findex p (nm)
The symbols are listed in the order as they appear in the object code
module.

@item -r
@findex r (nm)
The output is sorted in reverse ascii order.

@item -s
@findex s (nm)
Archives may contain a special member called @samp{__.SYMDEF}. Don't ask
me about it purpose. Anyway, using this option show the content of this
member.

@item -u
@findex u (nm)
Only undefined symbols are listed.
@end table

@node  cnm.ttp, gcc-size.ttp, gcc-nm.ttp, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsection @file{cnm.ttp}
@cindex cnm.ttp (executable)

  @file{cnm.ttp} prints the symbols which are attached to an executable.
This can be either a standard DRI or an extended symbol table. To list
the symbols in an object file or library use @file{gcc-nm.ttp}.  The
following options are supported by @file{cnm.ttp}:@refill

@table @samp
@cindex Options (cnm)
@item g
@findex g (cnm)
List only those symbols, which are flagged as global.

@item u
@findex u (cnm)
List the symbols in the order as they appear in the symbol table
(unsorted).
@end table

Without any options, all symbols, which appear in the symbols table, are
listed and sorted according to their value.

@node     gcc-size.ttp, printstk.ttp, cnm.ttp, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsection @file{gcc-size.ttp}
@cindex gcc-size.ttp (executable)
  @file{gcc-size.ttp} reports the sizes of the sections (text, data and
bss) in an GNU object file or library. @file{gcc-size.ttp} has no
additional options.

  The following example shows the output, when @file{gcc-size.ttp} is
executed with an object file and an object library as arguments:@refill

@example
c:\gnu\lib => gcc-size crt0.o iio.olb
text	data	bss	dec	hex
960	12	8	980	3d4	crt0.o
1580	0	0	1580	62c	iio.olb(idoprnt.o)
1884	0	0	1884	75c	iio.olb(iscanf.o)
116	0	0	116	74	iio.olb(fprintf.o)
164	0	0	164	a4	iio.olb(sprintf.o)
164	0	0	164	a4	iio.olb(fscanf.o)
144	0	0	144	90	iio.olb(sscanf.o)
@end example

The name in braces in the last column is the member of the library.

@node     printstk.ttp, fixstk.ttp, gcc-size.ttp, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsection @file{printstk.ttp}
@cindex printstk.ttp (executable)

@file{printstk.ttp} works basically the same way as @file{fixstk.ttp},
but displays the current value at the location @code{_stksize} or
@code{_initial_stack}. The usage is:@refill

@example
printstk @var{filename} @dots{}
@end example

If @file{printstk.ttp} is used on some of the executables of the GCC
distribution, you should see a value of @samp{-1}, which means that all
available memory is used by the program (at least for the programs
@file{gcc-cpp.ttp} and @file{gcc-cc1.ttp}).@refill

@node     fixstk.ttp, toglclr.ttp, printstk.ttp, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsection @file{fixstk.ttp}
@cindex fixstk.ttp (executable)

@file{fixstk.ttp} is used to modify the current stacksize of an
executable.  It does this by looking up the symbol @code{_stksize} in
the symbol table portion of the file and than changes the values of the
location where @code{_stksize} points to. The usage is:@refill
@cindex stksize
@cindex _stksize

@example
fixstk @var{size} @var{file} @dots{}
@end example

@var{size} is the stacksize in Bytes, KBytes or MBytes. To specify
@var{size} in Kbytes or Mbytes, append a @samp{K} or a @samp{M} to the
integer number.@refill

For dumping applications like Scott Kolodzieski's port of GNU Emacs
18.57 @file{fixstk.ttp} looks up the symbol @code{_initial_stack}
instead of @code{_stksize}.
@cindex initial_stack
@cindex _initial_stack

@example
fixstk 128K gcc-as.ttp
@end example

@noindent
sets the stacksize of @file{gcc-as.ttp} to 128 Kbytes.

@node     toglclr.ttp, xstrip.ttp, fixstk.ttp, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsection @file{toglclr.ttp}
@cindex toglclr.ttp (executable)

The general syntax to invoke @file{toglclr.ttp} is:

@example
toglclr [@var{options}] @var{file} @dots{}
@end example

@file{toglclr.ttp} supports the following options:

@table @samp
@item -fload
@findex fload (toglclr)
Toggle the @samp{fast load} flag.

@item -frun
@findex frun (toglclr)
Toggle the @samp{fast run} flag.

@item -fram
@findex fram (toglclr)
Toggle the @samp{fast ram malloc} flag.

@item -fshare
@findex fshare (toglclr)
Toggle the @samp{shared text} flag.

@item -private
@findex private (toglclr)
Set memory protection to @sc{Private}. Only the process itself and the
AES have access to the process's memory. This is the normal state.

@item -global
@findex global (toglclr)
Set memory protection to @sc{Global}. Every process has unrestricted
access to the process's memory.

@item -super
@findex super (toglclr)
Set memory protection to @sc{Super}. Every process in supervisor mode
has unrestricted access to the process's memory.

@item -readable
@findex readable (toglclr)
Set memory protection to @sc{Private/Readable}. Every process has access
to the process's memory, but only for read operations.
@end table

  The last four option are not yet part of the official
@file{toglclr.ttp}. I've send the changes to J.R.Bammi. They will
probably be part of an future update.

  If TOS launches an application, it clears all memory starting from the
BSS section to the end of the TPA. With earlier TOS versions (pre TOS
1.4) this could take quite a considerable amount of time. The clearing
algorithm was improved during the different TOS releases, but it is
still used, although @strong{most} of the existing programs don't need a
cleared memory. Well, most is not all; therefore for compatibility sake
the feature will stay in place.

  With TOS 1.4 you can keep the GEMDOS loader from clearing all memory.
The long word with offset 0x16 in the program header is used to
determine whether the memory should be cleared or not. Setting the bit 0
of this longword to 1 prevents the loader from clearing all memory.
@file{toglclr.ttp} serves exactly that purpose, namely toggling this
long word.@refill

  TOS 2.x and 3.x gave another two bits in the above mentioned longword
a meaning. The @samp{fast run} bit 1 is used to determine, if a program
should be started in ordinary ST-ram (bit 1 = 0) or in alternate ram. In
case of the TT or the SST68030 from Dave Small, this is ram which is not
slowed down by any video hardware.

  The @samp{fast ram malloc} bit 2 determines, if any subsequent
malloc's, which a program might do, should be satisfied from slow ST-ram
(bit 2 = 0) or from alterate ram. All these flags have been introduced
to increase compatibility between the different TOS versions.

  To toggle the @samp{shared text} bit only makes sense, if you'r using
MiNT 0.96 pl14 and higher or MultiTOS. An additional requirement is,
that the program is compiled with the GCC @samp{-mbaserel} option and
linked with the corresponding libraries. In essence this means, if the
@samp{shared text} bit is set, multiple processes of the same program
execute on the same text (program code) segment in memory.

  Using the options, which modify the memory protection of the program
shows only effect, if you're running MultiTOS on a machine with MMU
(M68030).

@node     xstrip.ttp, size68.ttp, toglclr.ttp, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsection @file{xstrip.ttp}
@cindex xstrip.ttp (executable)

  @file{xstrip.ttp} removes the symbol table from a TOS executable file.
The default behaviour, which is to completely remove the symbol table
(except the symbol @code{_stksize}), may be modified by specifying
additional command line optione. The systax for the @file{xstrip.ttp}
command is: @refill

@example
xstrip [-a] [-g] [-k] [-l @var{names}] [-t] @var{file} @dots{}
@end example

@table @samp
@item -a
@findex a (xstrip)
Specifying this option @emph{completely} removes the symbol table.

@item -g
@findex g (xstrip)
This option causes @file{xstrip.ttp} to keep all global symbols.

@item -k
@findex k (xstrip)
keeps the @code{_stksize} symbol, so that the stack size can be adjusted
even for a nearly-stripped GCC produced executables.

@item -l @var{names}
@findex l (xstrip)
keeps all symbols listed in a file @var{names} (one symbol per line).

@item -t
@findex t (xstrip)
to strip TurboC / PureC style executables.
@end table

Both @samp{-k} and @samp{-l} options convert the extended symbols into
regular ones (DRI compatible).

@node     size68.ttp,  , xstrip.ttp, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsection @file{size68.ttp}
@cindex size68.ttp (executable)

  @file{size68.ttp} is used to print information, which is found in the
the header of an executable program file. A sample output is shown in
the following lines.@refill

@example
c:\ => size68 temacs
temacs:
        text size       255448
        data size       161044
        bss size        7684
        symbol size     38388
        File is relocatable.
        BSS and high mem cleared on startup.
        File is loaded into alternate ram
         and allocates memory from alternate ram.
        File runs with `private' memory protection (under MultiTOS).
@end example

  The value of @samp{text size} is the actual size of the program code;
the TEXT segment. The value of @samp{data size} gives the size of
initialized data; the DATA segment. For example, if you define a
variable @samp{char array[10] = "foobar";}, the string @samp{foobar} is
moved to the data segment during the linking process. The value of
@samp{bss size} is the size of the BSS segment. If you define a global
variable @samp{char array[10];}, this variable @samp{array} would end up
the BSS segment. The BSS segment is initialized to zero from the GEMDOS
loader, when the program is loaded into memory. The memory usage during
the programs runtime can't simply be calculated by adding the three
values, since this doesn't take into account the memory, which might be
dynamically allocated.@refill

  The value of @samp{symbol table} is the size of the symbol table,
which is appended to the three segments. The symbol table is only used,
when the program is invoked under the control of a debugger. The symbol
table doesn't use up any memory, when the program is launched from the
desktop or a CLI. The next line says, that the program file is
relocatable. As far as I know is every program file relocatable on the
ST. The follwoing line indicates, that the BSS section and the all
available memory (@samp{high mem}) is cleared upon startup. On systems
with lots of memory, this can take quite a bit of time. You can keep the
GEMDOS loader from clearing all memory by toggling a bit in the header.
See @file{toglclr.ttp} for more info.@refill

@c  The last three lines report the status of the bits, which were
@c introduced with TOS 2.0x, 3.0x and MultiTOS.
@page

@node     Debugging, Concept Index, The Utilities, Top
@comment  node-name,  next,  previous,  up
@chapter Debugging Programs
@cindex Debugging
  In general, you have two choices for debugging; machine and source
level debugging. Most of the time you will prefer the source level
debugging.

@emph{This chapter is not ready yet. If you have some ideas, what should
go into this section, please tell me.}

Mention GDB 3.5 here.
@page

@c Print indices
@node     Concept Index, Command Options, Debugging, Top
@comment  node-name,     next,            previous,  up
@unnumbered Concept Index
@printindex cp
@page

@node     Command Options, , Concept Index, Top
@comment  node-name,  next,  previous,      up
@unnumbered Index of all Command Line Options
@printindex fn
@page

@contents

@bye

@c Local Variables:
@c eval: (require 'header)
@c auto-save-interval: 1000
@c End:
